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MODEL TRAIN CONTROL SYSTEM 

BACKGROUND OF THE INVENTION 

The present invention relates to a system for 
5 controlling a model railroad. 

Model railroads have traditionally been 
constructed with of a set of interconnected sections of 
train track, electric switches between different sections 
of the train track, and other electrically operated 

10 devices, such as train engines and draw bridges. Train 
engines receive their power to travel on the train track 
by electricity provided by a controller through the track 
itself. The speed and direction of the train engine is 
controlled by the level and polarity, respectively, of 

15 the electrical power supplied to the train track. The 

operator manually pushes buttons or pulls levers to cause 
the switches or other electrically operated devices to 
function, as desired. Such model railroad sets are 
suitable for a single operator, but unfortunately they 

20 lack the capability of adequately controlling multiple 
trains independently. In addition, such model railroad 
sets are not suitable for being controlled by multiple 
operators, especially if the operators are located at 
different locations distant from the model railroad, such 

25 as different cities. 

A digital command control (DDC) system has been 
developed to provide additional controllability of 
individual train engines and other electrical devices. 
Each device the operator desires to control, such as a 

30 train engine, includes an individually addressable 

digital decoder. A digital command station (DCS) is 
electrically connected to the train track to provide a 
command in the form of a set of encoded digital bits to a 
particular device that includes a digital decoder. The 

35 digital command station is typically controlled by a 

personal computer. A suitable standard for the digital 
command control system is the NMRA DCC Standards, issued 



March 1997, and is incorporated herein by reference. 
While providing the ability to individually control 
different devices of the railroad set, the DCC system 
still fails to provide the capability for multiple 
5 operators to control the railroad devices, especially if 
the operators are remotely located from the railroad set 
and each other. 

DigiToys Systems of Lawrenceville , Georgia has 
developed a software program for controlling a model 

10 railroad set from a remote location. The software 

includes an interface which allows the operator to select 
desired changes to devices of the railroad set that 
include a digital decoder, such as increasing the speed 
of a train or switching a switch. The software issues a 

15 command locally or through a network, such as the 

internet, to a digital command station at the railroad 
set which executes the command. The protocol used by the 
software is based on Cobra from Open Management Group 
where the software issues a command to a communication 

2 0 interface and awaits confirmation that the command was 
executed by the digital command station. When the 
software receives confirmation that the command executed, 
the software program sends the next command through the 
communication interface to the digital command station. 

25 In other words, the technique used by the software to 

control the model railroad is analogous to an inexpensive 
printer where commands are sequentially issued to the 
printer after the previous command has been executed. 
Unfortunately, it has been observed that the response of 

30 the model railroad to the operator appears slow, 
especially over a distributed network such as the 
internet. One technique to decrease the response time is 
to use high-speed network connections but unfortunately 
such connections are expensive. 

35 What is desired, therefore, is a system for 

controlling a model railroad that effectively provides a 



high-speed connection without the additional expense 
associated therewith. 

The foregoing and other objectives, features, 
and advantages of the invention will be more readily 
5 understood upon consideration of the following detailed 
description of the invention, taken in conjunction with 
the accompanying drawings . 

SUMMARY OF THE PRESENT INVENTION 

10 The present invention overcomes the 

aforementioned drawbacks of the prior art, in a first 
aspect, by providing a system for operating a digitally 
controlled model railroad that includes transmitting a 
first command from a first client program to a resident 

15 external controlling interface through a first 
communications transport. A second command is 
transmitted from a second client program to the resident 
external controlling interface through a second 
communications transport. The first command and the 

20 second command are received by the resident external 

controlling interface which queues the first and second 
commands. The resident external controlling interface 
sends third and fourth commands representative of the 
first and second commands, respectively, to a digital 

25 command station for execution on the digitally controlled 
model railroad. 

Incorporating a communications transport 
between the multiple client program and the resident 
external controlling interface permits multiple operators 

30 of the model railroad at locations distant from the 
physical model railroad and each other. In the 
environment of a model railroad club where the members 
want to simultaneously control devices of the same model 
railroad layout, which preferably includes multiple 

35 trains operating thereon, the operators each provide 

commands to the resistant external controlling interface, 
and hence the model railroad. In addition by queuing by 
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commands at a single resident external controlling 
interface permits controlled execution of the commands by 
the digitally controlled model railroad, would may 
otherwise conflict with one another. 
5 In another aspect of the present invention the 

first command is selectively processed and sent to one of 
a plurality of digital command stations for execution on 
the digitally controlled model railroad based upon 
information contained therein. Preferably, the second 

10 command is also selectively processed and sent to one of 
the plurality of digital command stations for execution 
on the digitally controlled model railroad based upon 
information contained therein. The resident external 
controlling interface also preferably includes a command 

15 queue to maintain the order of the commands. 

The command queue also allows the sharing of 
multiple devices, multiple clients to communicate with 
the same device (locally or remote) in a controlled 
manner, and multiple clients to communicate with 

20 different devices. In other words, the command queue 
permits the proper execution in the cases of: (1) one 
client to many devices, (2) many clients to one device, 
and (3) many clients to many devices. 

In yet another aspect of the present invention 

25 the first command is transmitted from a first client 
program to a first processor through a first 
communications transport. The first command is received 
at the first processor. The first processor provides an 
acknowledgement to the first client program through the 

3 0 first communications transport indicating that the first 
command has properly executed prior to execution of 
commands related to the first command by the digitally 
controlled model railroad. The communications transport 
is preferably a COM or DCOM interface. 

3 5 The model railroad application involves the use 

of extremely slow real-time interfaces between the 
digital command stations and the devices of the model 
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railroad. In order to increase the apparent speed of 
execution to the client, other than using high-speed 
communication interfaces, the resident external 
controller interface receives the command and provides an 
5 acknowledgement to the client program in a timely manner 
before the execution of the command by the digital 
command stations. Accordingly, the execution of commands 
provided by the resident external controlling interface 
to the digital command stations occur in a synchronous 

10 manner, such as a first -in- first -out manner. The COM and 
DCOM communications transport between the client program 
and the resident external controlling interface is 
operated in an asynchronous manner, namely providing an 
acknowledgement thereby releasing the communications 

15 transport to accept further communications prior to the 
actual execution of the command. The combination of the 
synchronous and the asynchronous data communication for 
the commands provides the benefit that the operator 
considers the commands to occur nearly instantaneously 

2 0 while permitting the resident external controlling 

interface to verify that the command is proper and cause 
the commands to execute in a controlled manner by the 
digital command stations, all without additional high- 
speed communication networks. Moreover, for traditional 
25 distributed software execution there is no motivation to 
provide an acknowledgment prior to the execution of the 
command because the command executes quickly and most 
commands are sequential in nature. In other words, the 
execution of the next command is dependent upon proper 

3 0 execution of the prior command so there would be no 

motivation to provide an acknowledgment prior to its 
actual execution . 

BRIEF DESCRIPTION OF THE SEVERAL VIEWS OF THE DRAWINGS 
35 FIG. 1 is a block diagram of an exemplary 

embodiment of a model train control system. 
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FIG. 2 is a more detailed block diagram of the 
model train control system of FIG. 1 including external 
device control logic. 

FIG. 3 is a block diagram of the external 
5 device control logic of FIG. 2. 

FIG. 4 is an illustration of a track and 
signaling arrangement. 

FIG. 5 is an illustration of a manual block 
signaling arrangement. 
10 FIG. 6 is an illustration of a track circuit. 

FIGS. 7A and 7B are illustrations of block 
signaling and track capacity. 

FIG. 8 is an illustration of different types of 

signals . 

15 FIGS. 9A and 9B are illustrations of speed 

signaling in approach to a junction. 

FIG. 10 is a further embodiment of the system 
including a dispatcher. 

2 0 DETAILED DESCRIPTION OF THE PREFERRED EMBODIMENT 

Referring to FIG. 1, a model train control 
system 10 includes a communications transport 12 
interconnecting a client program 14 and a resident 
external controlling interface 16. The client program 14 

25 executes on the model railroad operator's computer and 

may include any suitable system to permit the operator to 
provide desired commands to the resident external 
controlling interface 16. For example, the client 
program 14 may include a graphical interface 

30 representative of the model railroad layout where the 

operator issues commands to the model railroad by making 
changes to the graphical interface. The client program 
14 also defines a set of Application Programming 
Interfaces (API's), described in detail later, which the 

35 operator accesses using the graphical interface or other 
programs such as Visual Basic, C++, Java, or browser 
based applications. There may be multiple client 
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programs interconnected with the resident external 
controlling interface 16 so that multiple remote 
operators may simultaneously provide control commands to 
the model railroad. 
5 The communications transport 12 provides an 

interface between the client program 14 and the resident 
external controlling interface 16. The communications 
transport 12 may be any suitable communications medium 
for the transmission of data, such as the internet, local 

10 area network, satellite links, or multiple processes 

operating on a single computer. The preferred interface 
to the communications transport 12 is a COM or DCOM 
interface, as developed for the Windows operating system 
available from Microsoft Corporation. The communications 

15 transport 12 also determines if the resident external 

controlling interface 16 is system resident or remotely 
located on an external system. The communications 
transport 12 may also use private or public 
communications protocol as a medium for communications. 

2 0 The client program 14 provides commands and the resident 
external controlling interface 16 responds to the 
communications transport 12 to exchange information. 
A description of COM (common object model) and DCOM 
(distributed common object model) is provided by Chappel 

2 5 in a book entitled Understanding ActiveX and OLE, 

Microsoft Press, and is incorporated by reference herein. 

Incorporating a communications transport 12 
between the client program (s) 14 and the resident 
external controlling interface 16 permits multiple 

3 0 operators of the model railroad at locations distant from 

the physical model railroad and each other. In the 
environment of a model railroad club where the members 
want to simultaneously control devices of the same model 
railroad layout, which preferably includes multiple 
35 trains operating thereon, the operators each provide 

commands to the resistant external controlling interface, 
and hence the model railroad. 
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The manner in which commands are executed for 
the model railroad under COM and DCOM may be as follows. 
The client program 14 makes requests in a synchronous 
manner using COM/DCOM to the resident external interface 
5 controller 16. The synchronous manner of the request is 
the technique used by COM and DCOM to execute commands . 
The communications transport 12 packages the command for 
the transport mechanism to the resident external 
controlling interface 16. The resident external 

10 controlling interface 16 then passes the command to the 
digital command stations 18 which in turn executes the 
command. After the digital command station 18 executes 
the command an acknowledgement is passed back to the 
resident external controlling interface 16 which in turn 

15 passes an acknowledgement to the client program 14. Upon 
receipt of the acknowledgement by the client program 14, 
the communications transport 12 is again available to 
accept another command. The train control system 10, 
without more, permits execution of commands by the 

20 digital command stations 18 from multiple operators, but 
like the DigiToys Systems 1 software the execution of 
commands is slow. 

The present inventor came to the realization 
that unlike traditional distributed systems where the 

25 commands passed through a communications transport are 

executed nearly instantaneously by the server and then an 
acknowledgement is returned to the client, the model 
railroad application involves the use of extremely slow 
real-time interfaces between the digital command stations 

3 0 and the devices of the model railroad. The present 

inventor came to the further realization that in order to 
increase the apparent speed of execution to the client, 
other than using high-speed communication interfaces, the 
resident external controller interface 16 should receive 

3 5 the command and provide an acknowledgement to the client 
program 12 in a timely manner before the execution of the 
command by the digital command stations 18. Accordingly, 
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the execution of commands provided by the resident 
external controlling interface 16 to the digital command 
stations 18 occur in a synchronous manner, such as a 
first-in-first-out manner. The COM and DCOM 
5 communications transport 12 between the client program 14 
and the resident external controlling interface 16 is 
operated in an asynchronous manner, namely providing an 
acknowledgement thereby releasing the communications 
transport 12 to accept further communications prior to 

10 the actual execution of the command. The combination of 
the synchronous and the asynchronous data communication 
for the commands provides the benefit that the operator 
considers the commands to occur nearly instantaneously 
while permitting the resident external controlling 

15 interface 16 to verify that the command is proper and 

cause the commands to execute in a controlled manner by 
the digital command stations 18, all without additional 
high-speed communication networks. Moreover, for 
traditional distributed software execution there is no 

2 0 motivation to provide an acknowledgment prior to the 
execution of the command because the command executes 
quickly and most commands are sequential in nature. In 
other words, the execution of the next command is 
dependent upon proper execution of the prior command so 

2 5 there would be no motivation to provide an acknowledgment 

prior to its actual execution. It is to be understood 
that other devices, such as digital devices, may be 
controlled in a manner as described for model railroads. 

Referring to FIG. 2, the client program 14 

3 0 sends a command over the communications transport 12 that 

is received by an asynchronous command processor 100. 
The asynchronous command processor 100 queries a local 
database storage 102 to determine if it is necessary to 
package a command to be transmitted to a command queue 
35 104. The local database storage 102 primarily contains 
the state of the devices of the model railroad, such as 
for example, the speed of a train, the direction of a 



train, whether a draw bridge is up or down, whether a 
light is turned on or off, and the configuration of the 
model railroad layout. If the command received by the 
asynchronous command processor 100 is a query of the 
5 state of a device, then the asynchronous command 

processor 100 retrieves such information from the local 
database storage 102 and provides the information to an 
asynchronous response processor 106. The asynchronous 
response processor 106 then provides a response to the 
10 client program 14 indicating the state of the device and 
releases the communications transport 12 for the next 
command . 

The asynchronous command processor 10 0 also 
verifies, using the configuration information in the 

15 local database storage 102, that the command received is 
a potentially valid operation. If the command is 
invalid, the asynchronous command processor 100 provides 
such information to the asynchronous response processor 
106, which in turn returns an error indication to the 

2 0 client program 14. 

The asynchronous command processor 10 0 may 
determine that the necessary information is not contained 
in the local database storage 102 to provide a response 
to the client program 14 of the device state or that the 

2 5 command is a valid action. Actions may include, for 

example, an increase in the train's speed, or turning 
on/off of a device. In either case, the valid unknown 
state or action command is packaged and forwarded to the 
command queue 104. The packaging of the command may also 

3 0 include additional information from the local database 

storage 102 to complete the client program 14 request, if 
necessary. Together with packaging the command for the 
command queue 104, the asynchronous command processor 100 
provides a command to the asynchronous request processor 
35 106 to provide a response to the client program 14 

indicating that the event has occurred, even though such 
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an event has yet to occur on the physical railroad 
layout . 

As such, it can be observed that whether or not 
the command is valid, whether or not the information 
5 requested by the command is available to the asynchronous 
command processor 100, and whether or not the command has 
executed, the combination of the asynchronous command 
processor 100 and the asynchronous response processor 106 
both verifies the validity of the command and provides a 

10 response to the client program 14 thereby freeing up the 
communications transport 12 for additional commands. 
Without the asynchronous nature of the resident external 
controlling interface 16, the response to the client 
program 14 would be, in many circumstances, delayed 

15 thereby resulting in frustration to the operator that the 
model railroad is performing in a slow and painstaking 
manner. In this manner, the railroad operation using the 
asynchronous interface appears to the operator as nearly 
instantaneously responsive . 

2 0 Each command in the command queue 104 is 

fetched by a synchronous command processor 110 and 
processed. The synchronous command processor 110 queries 
a controller database storage 112 for additional 
information, as necessary, and determines if the command 

2 5 has already been executed based on the state of the 

devices in the controller database storage 112. In the 
event that the command has already been executed, as 
indicated by the controller database storage 112, then 
the synchronous command processor 110 passes information 

3 0 to the command queue 104 that the command has been 

executed or the state of the device. The asynchronous 
response processor 106 fetches the information from the 
command cue 104 and provides a suitable response to the 
client program 14, if necessary, and updates the local 
3 5 database storage 102 to reflect the updated status of the 
railroad layout devices. 
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If the command fetched by the synchronous 
command processor 110 from the command queue 104 requires 
execution by external devices, such as the train engine, 
then the command is posted to one of several external 
5 device control logic 114 blocks. The external device 
control logic 114 processes the command from the 
synchronous command processor 110 and issues appropriate 
control commands to the interface of the particular 
external device 116 to execute the command on the device 

10 and ensure that an appropriate response was received in 
response. The external device is preferably a digital 
command control device that transmits digital commands to 
decoders using the train track. There are several 
different manufacturers of digital command stations, each 

15 of which has a different set of input commands, so each 
external device is designed for a particular digital 
command station. In this manner, the system is 
compatible with different digital command stations. The 
digital command stations 18 of the external devices 116 

2 0 provide a response to the external device control logic 

114 which is checked for validity and identified as to 
which prior command it corresponds to so that the 
controller database storage 112 may be updated properly. 
The process of transmitting commands to and receiving 

25 responses from the external devices 116 is slow. 

The synchronous command processor 110 is 
notified of the results from the external control logic 
114 and, if appropriate, forwards the results to the 
command queue 104. The asynchronous response processor 

30 100 clears the results from the command queue 104 and 
updates the local database storage 102 and sends an 
asynchronous response to the client program 14, if 
needed. The response updates the client program 14 of 
the actual state of the railroad track devices, if 

3 5 changed, and provides an error message to the client 

program 14 if the devices actual state was previously 
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improperly reported or a command did not execute 
properly . 

The use of two separate database storages, each 
of which is substantially a mirror image of the other, 
5 provides a performance enhancement by a fast 

acknowledgement to the client program 14 using the local 
database storage 102 and thereby freeing up the 
communications transport 12 for additional commands. In 
addition, the number of commands forwarded to the 

10 external device control logic 114 and the external 

devices 116, which are relatively slow to respond, is 
minimized by maintaining information concerning the state 
and configuration of the model railroad. Also, the use 
of two separate database tables 102 and 112 allows more 

15 efficient multi -threading on multi-processor computers. 

In order to achieve the separation of the 
asynchronous and synchronous portions of the system the 
command queue 104 is implemented as a named pipe, as 
developed by Microsoft for Windows. The queue 104 allows 

20 both portions to be separate from each other, where each 
considers the other to be the destination device. In 
addition, the command queue maintains the order of 
operation which is important to proper operation of the 
system. 

25 The use of a single command queue 104 allows 

multiple instantrations of the asynchronous 
functionality, with one for each different client. The 
single command queue 104 also allows the sharing of 
multiple devices, multiple clients to communicate with 

30 the same device (locally or remote) in a controlled 
manner, and multiple clients to communicate with 
different devices. In other words, the command queue 104 
permits the proper execution in the cases of: (1) one 
client to many devices, (2) many clients to one device, 

3 5 and (3) many clients to many devices. 

The present inventor came to the realization 
that the digital command stations provided by the 
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different vendors have at least three different 
techniques for communicating with the digital decoders of 
the model railroad set. The first technique, generally 
referred to as a transaction (one or more operations) , is 
5 a synchronous communication where a command is 

transmitted, executed, and a response is received 
therefrom prior to the transmission of the next 
sequentially received command. The DCS may execute 
multiple commands in this transaction. The second 

10 technique is a cache with out of order execution where a 
command is executed and a response received therefrom 
prior to the execution of the next command, but the order 
of execution is not necessarily the same as the order 
that the commands were provided to the command station. 

15 The third technique is a local-area-network model where 

the commands are transmitted and received simultaneously. 
In the LAN model there is no requirement to wait until a 
response is received for a particular command prior to 
sending the next command. Accordingly, the LAN model may 

2 0 result in many commands being transmitted by the command 

station that have yet to be executed. In addition, some 
digital command stations use two or more of these 
techniques . 

With all these different techniques used to 
25 communicate with the model railroad set and the system 10 
providing an interface for each different type of command 
station, there exists a need for the capability of 
matching up the responses from each of the different 
types of command stations with the particular command 

3 0 issued for record keeping purposes. Without matching up 

the responses from the command stations, the databases 
can not be updated properly. 

Validation functionality is included within the 
external device control logic 114 to accommodate all of 
35 the different types of command stations. Referring to 
FIG. 3, an external command processor 2 00 receives the 
validated command from the synchronous command processor 



15 

110. The external command processor 200 determines which 
device the command should be directed to, the particular 
type of command it is, and builds state information for 
the command. The state information includes, for 
5 example, the address, type, port, variables, and type of 
commands to be sent out. In other words, the state 
information includes a command set for a particular 
device on a particular port device. In addition, a copy 
of the original command is maintained for verification 

10 purposes. The constructed command is forwarded to the 

command sender 2 02 which is another queue, and preferably 
a circular queue. The command sender 202 receives the 
command and transmits commands within its queue in a 
repetitive nature until the command is removed from its 

15 queue. A command response processor 204 receives all the 
commands from the command stations and passes the 
commands to the validation function 206. The validation 
function 2 06 compares the received command against 
potential commands that are in the queue of the command 

20 sender 202 that could potentially provide such a result. 
The validation function 206 determines one of four 
potential results from the comparison. First, the 
results could be simply bad data that is discarded. 
Second, the results could be partially executed commands 

2 5 which are likewise normally discarded. Third, the 

results could be valid responses but not relevant to any 
command sent. Such a case could result from the operator 
manually changing the state of devices on the model 
railroad or from another external device, assuming a 

3 0 shared interface to the DCS. Accordingly, the results 

are validated and passed to the result processor 210. 
Fourth, the results could be valid responses relevant to 
a command sent. The corresponding command is removed 
from the command sender 2 02 and the results passed to the 
35 result processor 210. The commands in the queue of the 

command sender 202, as a result of the validation process 
2 06, are retransmitted a predetermined number of times, 
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then if error still occurs the digital command station is 
reset, which if the error still persists then the command 
is removed and the operator is notified of the error. 



5 APPLICATION PROGRAMMING INTERFACE 

Train ToolsTM Interface Description 
Biiilding your own visual interface to a model railroad 
Copyright 1992-1998 KAM Industries. 

Computer Dispatcher, Engine Commander, The Conductor, 
10 Train Server, and Train Tools are Trademarks of KAM 
Industries, all Rights Reserved. 

Questions concerning the product can be EMAILED to: 
traintools@kam. rain. com 
You can also mail questions to: 
15 KAM Industries 

2373 NW 185th Avenue Suite 416 
Hillsboro, Oregon 9712 4 
FAX - (503) 291-1221 
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I . OVERVIEW 

This document is divided into two sections, the 
Tutorial, -and the IDL Command Reference. The tutorial 
shows the complete code for a simple Visual BASIC program 
that controls all the major functions of a locomotive. 
This program makes use of many of the commands described 
in the reference section. The IDL Command Reference 
describes each command in detail. 

I . TUTORIAL 

A. Visual BASIC Throttle Example Application 

The following application is created using the 
Visual BASIC source code in the next section. It 
controls all major locomotive functions such as speed, 
direction, and auxiliary functions. 
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Visual BASIC Throttle Example Source Code 

Copyright 1998, KAM Industries. All rights reserved. 

This is a demonstration program showing the 
integration of VisualBasic and Train Server (tm) 
interface. You may use this application for non 
commercial usage. 

$Date: $ 
$Author : $ 
$Revision: $ 
$Log : $ 

Engine Commander, Computer Dispatcher, Train Server, 
Train Tools, The Conductor and kamind are registered 
Trademarks of KAM Industries. All rights reserved. 

This first command adds the reference to the Train 
ServerT Interface object Dim EngCmd As New EngComlfc 

Engine Commander uses the term Ports, Devices and 
Controllers 

Ports -> These are logical ids where Decoders are 
assigned to. Train ServerT Interface supports a 
limited number of logical ports. You can also think 
of ports as mapping to a command station type. This 
allows you to move decoders between command station 
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without losing any information about the decoder 

Devices -> These are communications channels 
configured in your computer. 

You may have a single device (coml) or multiple 
devices 

(COM 1 - COM8, LPT1, Other) . You are required to 
map a port to a device to access a command station. 
Devices start from ID 0 -> max id (FYI; devices do 
not necessarily have to be serial channel. Always 
check the name of the device before you use it as 
well as the maximum number of devices supported. 
The Command 

EngCmd. KamPortGetMaxPhysical (IMaxPhysical , lSerial , 
lParallel) provides means that... IMaxPhysical = 
1 Serial + lParallel + lOther 

Controller - These are command the command station 
like LENZ, Digit rax 

Northcoast, EasyDCC, Marklin. . . It is recommend 
that you check the command station ID before you 
use it. 



Errors - All commands return an error status. If 
25 1 the error value is non zero, then the 

other return arguments are invalid. In 
general , non zero errors means command was 
not executed. To get the error message, 
you need to call KamMiscErrorMessage and 
3 0 ' supply the error number 

To Operate your layout you will need to perform a 
mapping between a Port (logical reference) , Device 
(physical communications channel) and a Controller 

3 5 ' (command station) for the program to work. All 
references uses the logical device as the reference 
device for access . 

Addresses used are an object reference. To use an 

4 0 • address you must add the address to the command 
station using KamDecoderPutAdd . . . One of the return 
values from this operation is an object reference 
that is used for control. 

45 1 We need certain variables as global objects; since 

the information is being used multiple times 

Dim iLogicalPort , iController, iComPort 
Dim iPortRate, iPortParity, iPortStop, iPortRetrans , 
50 iPortWatchdog, iPortFlow, iPortData 

Dim lEngineObject As Long, iDecoderClass As Integer, 
iDecoderType As Integer 
Dim lMaxCont roller As Long 

Dim lMaxLogical As Long, IMaxPhysical As Long, lMaxSerial 
55 As Long, iMaxParallel As Long 

r******************************** 
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'Form load function 

1 - Turn of the initial buttons 

1 - Set he interface information 
• ******************************** 



10 



15 



20 



25 



30 



35 



40 



45 



50 



55 



Private Sub Form_load() 

Dim strVer As String, strCom As String, strCntrl As 

String 
Dim iError As Integer 

'Get the interface version information 
SetBut tonS t ate (False) 

iError = EngCmd . KamMiscGetlnterf aceVersion (strVer) 
If (iError) Then 

MsgBox (("Train Server not loaded. Check 

DCOM-95" ) ) 
iLogicalPort = 0 
LogPort . Caption = iLogicalPort 
ComPort . Caption = "???" 
Controller . Caption = "Unknown" 



Else 



MsgBox (( "Simulation (COM1) Train Server -- * 
strVer) ) 

************************************** 
Configuration information; Only need to 
change these values to use a different 
controller . . . 
************************************** 



0 // Unknown control type 

1 // Interface simulator 

2 // Lenz serial support module 

3 // Lenz serial support module 

4 // Digitrax direct drive 
support using DT2 00 

5 // Digitrax direct drive 
support using DCS100 

6 // North Coast engineering 
master Series 

7 // System One 

8 // RAM F I xx system 

9 // Dynatrol system 
Northcoast binary 10 // North Coast binary 



UNKNOWN 
SIMULAT 
LENZ_lx 
LENZ_2x 
DIGIT_DT200 

DIGIT_DCS100 

MASTERSERIES 

SYSTEMONE 

RAMFIX 

DYNATROL 



SERIAL 

EASYDCC 
MRK60 5 0 

MRK6 023 

ZTC 

DIGIT_PR1 
DIRECT 



11 // NMRA Serial 

interface 

12 // NMRA Serial interface 

13 // 6050 Marklin interface 

(AC and DC) 

14 // 6023 Marklin hybrid 

interface (AC) 

15 // ZTC Systems ltd 

16 // Digitrax direct drive 

support using PR1 

17 // Direct drive interface 

routine 



i******************************************************** 



1 1 

' 2 

' 3 

25 1 4 
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iLogicalPort = 1 'Select Logical port 1 for 

communications 
iController = 1 'Select controller from the list 

above . 

5 iComPort = 0 ' use C0M1; 0 means coml (Digitrax must 

use Coml or Com2) 
'Digitrax Baud rate requires 16. 4K! 
'Most COM ports above Com2 do not 
'support 16. 4K. Check with the 

10 'manufacture of your smart com card 

'for the baud rate. Keep in mind that 
'Dumb com cards with serial port 
' support Coml - Com4 can only support 
! 2 com ports (like coml/com2 

15 1 or com3/com4) 

'If you change the controller, do not 
1 forget to change the baud rate to 
'match the command station. See your 
'user manual for details 

20 ' *****************************^ 

' 0: // Baud rate is 300 
// Baud rate is 1200 
// Baud rate is 2400 
// Baud rate is 4800 
// Baud rate is 9600 
' 5: // Baud rate is 14.4 
' 6: // Baud rate is 16.4 
' 7: // Baud rate is 19.2 
iPortRate = 4 

3 0 1 Parity values 0-4 -> no, odd, even, mark, 

space 
iPortParity = 0 

Stop bits 0,1,2 -> 1, 1.5, 2 
iPortStop = 0 
3 5 iPortRetrans =10 

iPortWatchdog = 2 04 8 
iPortFlow = 0 

1 Data bits 0 - > 7 Bits, l-> 8 bits 
iPortData = 1 

40 

'Display the port and controller information 
iError = EngCmd . KamPortGetMaxLogPorts (lMaxLogical ) 
iError = EngCmd . KamPortGetMaxPhysical (IMaxPhysical , 
IMaxSerial, IMaxParal lei ) 

45 

1 Get the port name and do some checking. . . 
iError = EngCmd . KamPortGetName ( iComPort , strCom) 
SetError (iError) 

If (iComPort > IMaxSerial) Then MsgBox ("Com port 
5 0 our of range") 

iError = 

EngCmd . KamMi scGet Control lerName ( iCont rol 1 er , 
strCntrl) 
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If (iLogicalPort > lMaxLogical) Then MsgBox 
("Logical port out of range") 
SetError (iError) 

End If 

5 

1 Display values in Throttle.. 
LogPort . Caption = iLogicalPort 
ComPort . Capt ion = s t rCom 
Controller . Caption = strCntrl 

10 

End Sub 



i ****************************** 
15 'Send Command 
'Note : 

' Please follow the command order. Order is important 

1 for the application to work! 

i ****************************** 

20 Private Sub Command__Click ( ) 

1 Send the command from the interface to the command 
station, use the engineObject 
Dim iError, iSpeed As Integer 
If Not Connect . Enabled Then 
25 'TrainTools interface is a caching interface. 

This means that you need to set up the CV's or 
other operations first; then execute the 
command . 
iSpeed = Speed. Text 
3 0 iError = 

EngCmd . KamEngPut Funct ion ( lEngineOb j ect , 0 , FO . Value ) 
iError = 

EngCmd . KamEngPut Funct ion (lEngineObj ect, 1 , 
Fl .Value) 

3 5 iError = 

EngCmd. KamEngPut Funct ion (lEngineObj ect , 2 , 
F2 .Value) 
iError = 

EngCmd. KamEngPut Funct ion (lEngineObj ect , 3 , 

4 0 F3. Value) 

iError = EngCmd . KamEngPut Speed ( lEngineObj ect , 
iSpeed, Direction . Value) 
If iError = 0 Then iError = 
EngCmd . KamCmdCommand (lEngineObj ect ) 
45 SetError (iError) 

End If 

End Sub 

50 1 ****************************** 

' Connect Controller 
******************************* 

Private Sub Connect_Click ( ) 
Dim iError As Integer 
55 'These are the index values for setting up the port 

for use 



10 



15 



20 



25 



30 



35 



40 



45 



50 



55 
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PORT RETRANS 


0 


// 


Retrans 


index 


PORT RATE 


1 


// 


Retrans 


index 


PORT PARITY 


2 


// 


Retrans 


index 


PORT STOP 


3 


ii 


Retrans 


index 


PORT WATCHDOG 


4 


ii 


Retrans 


index 


PORT FLOW 


5 


ii 


Retrans 


index 


PORT DATABITS 


6 


ii 


Retrans 


index 


PORT DEBUG 


7 


ii 


Retrans 


index 


PORT PARALLEL 


8 


ii 


Retrans 


index 


'These are the 


index 


values for setting up the 


port for use 










PORT RETRANS 


0 


ii 


Retrans 


index 


PORT RATE 


1 


ii 


Retrans 


index 


PORT~PARITY 


2 


ii 


Retrans 


index 


PORT~STOP 


3 


ii 


Retrans 


index 


PORT WATCHDOG 


4 


ii 


Retrans 


index 


PORT FLOW 


5 


ii 


Retrans 


index 


PORT DATABITS 


6 


ii 


Retrans 


index 


PORT DEBUG 


7 


ii 


Retrans 


index 


PORT PARALLEL 


8 


ii 


Retrans 


index 



iError = EngCmd. KamPortPutConf ig (iLogicalPort , 0, 
iPortRetrans, 0) 1 setting PORT_RETRANS 
Error = EngCmd. KamPortPutConf ig (iLogicalPort , 1, 
PortRate, 0) ' setting PORT_RATE 
iError = EngCmd. KamPortPutConf ig (iLogicalPort , 2, 
iPortParity, 0) • setting PORT_PARITY 
iError = EngCmd . KamPortPutConf ig (iLogicalPort , 3, 
i Port Stop, 0) 1 setting PORT_STOP 

iError = EngCmd . KamPortPutConf ig (iLogicalPort , 4, 
iPortWatchdog, 0) 1 setting PORT_WATCHDOG 
iError = EngCmd . KamPortPutConf ig (iLogicalPort , 5, 
i Port Flow, 0) ■ setting P0RT_FLOW 

iError = EngCmd. KamPortPutConf ig (iLogicalPort , 6, 
iPortData, 0) ■ setting PORT_DATAB ITS 

We need to set the appropriate debug mode for display. , 
this command can only be sent if the following is true 
-Controller is not connected 
-port has not been mapped 

-Not share ware version of application (Shareware 

always set to 13 0) 
Write Display Log Debug 



File 



Win 



Level 
4 = 



1 
1 



+ 2 + 
queues 

+ 2 + 8 = 
send to window 
+ 2 + 16 = 
+ 2 + 32 



Value 
7 

11 



19 
35 



> LEVEL 1 

■> LEVEL2 

•> LEVEL 3 
-> LEVEL4 



semaphores/critical sections 

+ 2 + 64 = 67 -> LEVELS - 

debugging information 

+ 2 + 128 = 131 -> COMMONLY 

comm ports 



- put packets into 

- Status messages 

- All system 

- detailed 

Read comm write 
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You probably only want to use values of 130. This will 
give you a display what is read or written to the 
controller. If you want to write the information to 
disk, use 131. The other information is not valid for 
end users . 

Note: 1. This does effect the performance of you 

system; 13 0 is a save value for debug 
display. Always set the key to 1, a value 
10 1 of 0 will disable debug 

2 . The Digitrax control codes displayed are 

encrypted. The information that you 
determine from the control codes is that 
information is sent (S) and a response is 
15 ' received (R) 

iDebugMode = 13 0 

iValue = Value. Text' Display value for reference 
iError = EngCmd . KamPortPutConf ig ( iLogicalPort , 7, iDebug, 
2 0 i Value) 1 setting PORT_DEBUG 

'Now map the Logical Port, Physical device, Command 

station and Controller 
iError = EngCmd . KamPortPutMapController ( iLogicalPort , 
25 iController, iComPort) 

iError = EngCmd . KamCmdConnect (iLogicalPort). 

iError = EngCmd . KamOprPutTurnOnStat ion (iLogicalPort ) 

If (iError) Then 

SetButtonState (False) 
30 Else 

SetButtonState (True) 
End If 

SetError (iError) 'Displays the error message and error 
number 

35 

End Sub 

•Set the address button 

• ****************************** 

4 0 Private Sub DCCAddr_Click ( ) 

Dim iAddr, iStatus As Integer 

• All addresses must be match to a logical port to 
operate 

iDecoderType = 1 ' Set the decoder type to an NMRA 
45 baseline decoder (1-8 reg) 

iDecoderClass = 1 • Set the decoder class to Engine 
decoder (there are only two classes of decoders; 
Engine and Accessory 

50 'Once we make a connection, we use the lEngineObj ect 

'as the reference object to send control information 
If (Address .Text > 1) Then 

iStatus = EngCmd . KamDecoderPutAdd (Address . Text , 
iLogicalPort, iLogicalPort, 0, 
55 iDecoderType, lEngineObj ect ) 

SetError (iStatus) 
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If (lEngineObject) Then 

Command. Enabled = True 'turn on the control 
(send) button 

Throttle . Enabled = True ' Turn on the throttle 
5 Else 

MsgBox ("Address not set, check error message") 
End If 

Else 

MsgBox ("Address must be greater then 0 and 
10 less then 128") 

End If 

End Sub 

15 i ****************** * 

' Disconenct button 
i ******************* 

Private Sub Disconnect_Click ( ) 

Dim iError As Integer 
20 iError = EngCmd . KamCmdD is Connect ( iLogicalPort ) 

SetError (iError) 

SetButtonState (False) 
End Sub 

i ********************** 

25 'Display error message 
i ********************** 

Private Sub SetError (iError As Integer) 
Dim szError As String 
Dim iStatus 

3 0 ' This shows how to retrieve a sample error message 

from the interface for the status received. 
iStatus = EngCmd. KamMiscGetErrorMsg (iError, szError) 
ErrorMsg . Caption = szError 
Result . Caption = Str (iStatus) 

3 5 End Sub 

i ************************** 

1 Set the Form button state 
• ************************** 

Private Sub SetButtonState (iState As Boolean) 
40 'We set the state of the buttons; either connected 

or disconnected 
If (iState) Then 

Connect . Enabled = False 
Disconnect . Enabled = True 

4 5 ONCmd. Enabled = True 

Of fCmd. Enabled = True 
DCCAddr .Enabled = True 
UpDownAddress . Enabled = True 
■Now we check to see if the Engine Address has been 
50 'set; if it has we enable the send button 

If (lEngineObject > 0) Then 
Command. Enabled = True 
Throttle. Enabled = True 
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Else 

Command. Enabled = False 
Throttle. Enabled = False 
End If 
5 Else 

Connect . Enabled = True 
Disconnect . Enabled = False 
Command. Enabled = False 
ONCmd. Enabled = False 
10 Of fCmd. Enabled = False 

DCCAddr .Enabled = False 
UpDownAddress . Enabled = False 
Throttle. Enabled = False 
End If 

15 End Sub 

i ******************* 

'Power Off function 
« ******************* 

Private Sub Of f Cmd_Click ( ) 
2 0 Dim iError As Integer 

iError = EngCmd . KamOprPutPowerOf f ( iLogicalPort ) 
SetError (iError) 
End Sub 

• ****************** 

2 5 'Power On function 
i ****************** 

Private Sub ONCmd_Click ( ) 
Dim iError As Integer 

iError = EngCmd . KamOprPutPowerOn ( iLogicalPort ) 
30 SetError (iError) 

End Sub 

» ************************ 

'Throttle slider control 
35 i ************************ 

Private Sub Throttle_Click ( ) 
If (lEngineObject) Then 

If (Throttle. Value > 0) Then 
Speed. Text = Throttle .Value 
40 End If 

End If 

End Sub 



4 5 I. IDL COMMAND REFERENCE 

A. Introduction 

This document describes the IDL interface to 
50 the KAM Industries Engine Commander Train Server. The 
Train Server DCOM server may reside locally or. on a 
network node This server handles all the background 
details of controlling your railroad. You write simple, 
front end programs in a variety of languages such as 
55 BASIC, Java, or C++ to provide the visual interface to 
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the user while the server handles the details of 
communicating with the command station, etc. 

A. Data Types 

5 

Data is passed to and from the IDL interface using a 
several primitive data types. Arrays of these simple 
types are also used. The exact type passed to and from 
your program depends on the programming language your are 
10 using. 

The following primitive data types are used: 

IDL Type BASIC Type C++ Type Java Type Description 

15 short short short short Short signed integer 

int int int int Signed integer 

BSTR BSTR BSTR BSTR Text string 

long long long long Unsigned 3 2 bit value 

20 Name ID CV Range Valid CVs Functions Address Range Speed 
Steps 

NMRA Compatible 0 None None 2 1-99 14 

Baseline 1 1-8 1-8 9 1-127 14 

Extended 2 1-106 1-9, 17, 18, 19, 23, 24, 29, 30, 
25 49, 66-95 9. 1-10239 14,28,128 

All Mobile 3 1-106 1-106 9 1-10239 14,28,128 

Name ID CV Range Valid CVs Functions Address Range 
Accessory 4 513-593 513-593 8 0-511 

30 All Stationary 5 513-1024 513-1024 8 0-511 

A long /DecoderObj ect/D value is returned by the 
KamDecoderPutAdd call if the decoder is successfully 
registered with the server. This unique opaque ID should 
35 be used for all subsequent calls to reference this 
decoder . 
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Commands to access the server configuration variable 
database 



This section describes the commands that access 
the server configuration variables (CV) database. These 
CVs are stored in the decoder and control many of its 
characteristics such as its address. For efficiency, a 
4 5 copy of each CV value is also stored in the server 
database . Commands such as KamCVGetValue and 
KamCVPut Value communicate only with the server, not the 
actual decoder. You then use the programming commands in 
the next section to transfer CVs to and from the decoder. 

50 



OKamCVGetValue 

Parameter List Type Range Direction ■ Description 
lDecoderObjectlD long 1 In Decoder object ID 

iCVRegint 1-1024 2 In CV register 

5 pCWalue int * 3 Out Pointer to CV value 

1 Opaque object ID handle returned by 
KamDecoderPut Add . 

2 Range is 1-1024. Maximum CV for this decoder is 
given by KamCVGetMaxRegister . 

10 3 CV Value pointed to has a range of 0 to 255. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . KamCVGetValue takes the 

15 decoder object ID and configuration variable (CV) number 
as parameters. It sets the memory pointed to by pCWalue 
to the value of the server copy of the configuration 
variable . 

2 0 OKamCVPut Value 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

iCVRegint 1-1024 2 In CV register 

iCWalue int 0-255 In CV value 

2 5 1 Opaque object ID handle returned by 

KamDecoderPut Add . 

2 Maximum CV is 1024 . Maximum CV for this decoder is 
given by KamCVGetMaxRegister. 

Return Value Type Range Description 

3 0 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamCVPutValue takes the decoder object ID, configuration 
variable (CV) number, and a new CV value as parameters. 
3 5 It sets the server copy of the specified decoder CV to 
iCWalue. 

0 KamCVGe t Enab 1 e 

Parameter List Type Range Direction Description 
40 lDecoderObjectlD long 1 In Decoder object ID 

iCVRegint 1-1024 2 In CV number 

pEnable int * 3 Out Pointer to CV bit mask 

1 Opaque object ID handle returned by 

KamDecoderPutAdd . 
45 2 Maximum CV is 1024. Maximum CV for this decoder is 

given by KamCVGetMaxRegister. 

3 0x00 01 - SET_CV_INUSE 0x00 02 - SET_CV_READ_DIRTY 
0x0004 - SET_CV_WRITE_DIRTY 0x0008 - 
SET_CV_ERROR_READ 

50 0x0010 - SET_CV_ERROR_WRITE 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . KamCVGe t Enable takes the 
55 decoder object ID, configuration variable (CV) number, 
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and a pointer to store the enable flag as parameters, 
sets the location pointed to by pEnable. 



It 
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OKamCVPutEnable 

Parameter List Type Range 

iDecoderObj ectID long 

iCVRegint ~ 1-1024 2 

iEnableint 3 In 



Direction Description 
1 In Decoder object ID 
In CV number 
CV bit mask 



1 Opaque object ID handle returned by 
1 0 KamDecoderPut Add . 

2 Maximum CV is 1024. Maximum CV for this decoder is 
given by KamCVGetMaxRegister . 

3 0x00 01 - SET__CV_INUSE 0x00 02 - SET_CV_READ_DIRTY 
0x0004 - SET_CV_WRITE_DIRTY 0x0008 - 

1 5 SET_CVJ3RROR_READ 

0x0 010 - SET__CV_ERROR_WRITE 
Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
2 0 (see KamMiscGetErrorMsg) . 

KamCVPut Enable takes the decoder object ID, configuration 
variable (CV) number, and a new enable state as 
parameters. It sets the server copy of the CV bit mask 
to iEnable. 

OKamCVGetName 

Parameter List Type Range Direction Description 
iCV int 1-1024 In ^ CV number 

pbsCVNameString BSTR * 1 Out Pointer to CV 

name string 

1 Exact return type depends on language . It is 

Cstring * for C++. Empty string on error. 
Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamCVGetName takes a configuration variable (CV) number 
as a parameter. It sets the memory pointed to by 
pbsCVNameString to the name of the CV as defined in NMRA 
40 Recommended Practice RP 9.2.2. 



0 KamC VGe t M i nReg i s t e r 

Parameter List Type Range Direction Description 
IDecoderObj ectID long 1 In Decoder object ID 

45 pMinRegister int * 2 Out Pointer to min CV 

register number 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Normally 1-1024. 0 on error or if decoder does not 
5 0 support CVs . 

Return Value 
iError short 
1 iError = 
(see KamMiscGetErrorMsg) 



Type Range Description 

1 Error flag 
0 for success. Nonzero is an error number 
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KamCVGetMinRegister takes a decoder object ID as a 
parameter. It sets the memory pointed to by pMinRegister 
to the minimum possible CV register number for the 
specified decoder. 

5 

0 KamCVGe t MaxReg i s t e r 

Parameter List Type Range Direction Description 
iDecoderObj ectID long 1 In Decoder object ID 

pMaxRegister int * 2 Out Pointer to max CV 

10 register number 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Normally 1-1024. 0 on error or if decoder does not 
support CVs . 

15 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamCVGetMaxRegister takes a decoder object ID as a 
2 0 parameter. It sets the memory pointed to by pMaxRegister 
to the maximum possible CV register number for the 
specified decoder. 



2 5 A. Commands to program configuration variables 
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This section describes the commands read and 
write decoder configuration variables (CVs) . You should 
initially transfer a copy of the decoder CVs to the 
server using the KamProgramReadDecoderToDataBase command. 
You can then read and modify this server copy of the CVs. 
Finally, you can program one or more CVs into the decoder 
using the KamProgramCV or KamProgramDecoderFromDataBase 
command. Not that you must first enter programming mode 
by issuing the KamProgram command before any programming 
can be done. 
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0 KamProgram 

Parameter List Type Range 

IDecoderObj ectID long 

iProgLogPort int 1-6553 5 



iProgMode int 3 In 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

3 0 PROGRAM_M0DE_NONE 

1 - PROGRAM_MODE_ADDRESS 2 

PROGRAM_MODE_REGISTER 

3 - PROGRAM_MODE_PAGE 

4 - PROGRAM_MODE_DIRECT 

5 - DCODE_PRGMODE_OPS_SHORT 

6 - PROGRAM MODE OPS LONG 



Direction Description 

1 In Decoder object ID 

2 In Logical 

programming 
port ID 
Programming mode 



Return Value Type Range Description 

i Error short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

(see KamMiscGetErrorMsg) . 
5 KamProgram take the decoder object ID, logical 

programming port ID, and programming mode as parameters. 
It changes the command station mode from normal operation 

(PROGRAM_MODE__NONE) to the specified programming mode. 
Once in programming modes, any number of programming 
10 commands may be called. When done, you must call 

KamProgram with a parameter of PR0GRAM_M0DE_N0NE to 
return to normal operation. 

OKamProgramGetMode 
15 Parameter List Type Range Direction Description 

IDecoderObjectID long 1 In Decoder object ID 

iProgLogPort int 1-65535 2 In Logical 

programming 
port ID 

2 0 piProgMode int * 3 Out Programming mode 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

25 3 0 - PROGRAM_MODE_NONE 

1 - PROGRAM_MODE_ADDRESS 2 

PROGRAM JVIODEJREGI STER 

3 " - PROGRAM_MODE_PAGE 

4 - PROGRAM _M0DE_D I RECT 

3 0 5 DCODE_PRGMODE_OPS_SHORT 

6 . - PROGRAM_MODE__0 P S__LONG 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

3 5 (see KamMiscGetErrorMsg) . 

KamProgramGetMode take the decoder object ID, logical 
programming port ID, and pointer to a place to store 
the programming mode as parameters. It sets the memory 
pointed to by piProgMode to the present programming mode. 

40 

0 KamProgramGe t S t a tus 

Parameter List Type Range Direction Description 
IDecoderObjectID long 1 In Decoder object ID 

iCVRegint 0-1024 2 . In CV number 

45 piCVAHStatus int * 3 Out Or'd decoder programming 

status 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 0 returns OR'd value for all CVs. Other values 
50 return status for just that CV. 

3 0x00 01 - SET_CV_INUSE 
0x0002 - - SET_CV_READ_DIRTY 
0x0 004 - SET_CV_WRITE_DIRTY 
0x00 0 8 - SET_CV_ERROR_READ 

55 0x0010 - SET_CV_ERROR__WRITE 



Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
5 KamProgramGetStatus take the decoder object ID and 

pointer to a place to store the OR'd decoder programming 
status as parameters. It sets the memory pointed to by 
piProgMode to the present programming mode. 

10 OKamProgramReadCV 

Parameter List Type Range Direction Description 
lDecoderObj ect ID long 1 In Decoder object ID 

iCVRegint 2 In CV number 

1 Opaque object ID handle returned by 
15 KamDecoderPut Add . 

2 Maximum CV is 1024. Maximum CV for this decoder is 
given by KamCVGetMaxRegister . 

Return Value Type Range Description 

iError short 1 Error flag 

20 1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamProgramCV takes the decoder object ID, configuration 
variable (CV) number as parameters. It reads the 
specified CV variable value to the server database. 

25 

OKamProgramCV 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

iCVRegint 2 In CV number 

30 iCWalue int 0-255 In CV value 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum CV is 1024. Maximum CV for this decoder is 
given by KamCVGetMaxRegister. 

35 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamProgramCV takes the decoder object ID, configuration 
40 variable (CV) number, and a new CV value as parameters. 
It programs (writes) a single decoder CV using the 
specified value as source data. 

OKamProgramReadDecoderToDataBase 
45 Parameter List Type Range Direction Description 

lDecoderObjectlD long 1 In Decoder object ID 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

Return Value Type Range Description 

50 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) , 

KamProgramReadDecoderToDataBase takes the decoder object 
ID as a parameter. It reads all enabled CV values from 
55 the decoder and stores them in the server database. 
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OKamProgramDecoderFromDataBase 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamProgramDecoderFromDataBase takes the decoder object ID 
as a parameter. It programs (writes) all enabled decoder 
CV values using the server copy of the CVs as source 
data . 



A. Commands to control all decoder types 

This section describes the commands that all 
decoder types. These commands do things such getting the 
maximum address a given type of decoder supports, adding 
decoders to the database, etc. 

0 KamDecoderGe t MaxMode 1 s 

Parameter List Type Range Direction Description 
piMaxModels int * 1 Out Pointer to Max 

model ID 

1 Normally 1-65535. 0 on error. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamDecoderGe tMaxModels takes no parameters. It sets the 
memory pointed to by piMaxModels to the maximum decoder 
type ID. 

0 KamDe c ode r Ge t Mode lName 

Parameter List Type Range Direction Description 
iModel int 1-6553 5 1 In Decoder type ID 

pbsModelName BSTR * 2 Out Decoder name 

string 

1 Maximum value for this server given by 
KamDecoderGe tMaxModels . 

2 Exact return type depends on language. It is 
Cstring * for C++. Empty string on error. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError - 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . KamPortGetModelName takes a 
decoder type ID and a pointer to a string as parameters. 
It sets the memory pointed to by pbsModelName to a BSTR 
containing the decoder name. 
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0 KamDe code r S e t Mode 1 ToOb j 

Parameter List Type Range Direction Description 
iModel int 1 In Decoder model ID 

lDecoderObjectlD long 1 In Decoder object ID 

5 1 Maximum value for this server given by 
KamDecoderGetMaxModels . 

2 Opaque object ID handle returned by 
KamDecoderPutAdd . 

Return Value Type Range Description 

10 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamDecoderSetModelToObj takes a decoder ID and decoder 
object ID as parameters. It sets the decoder model type 
15 of the decoder at address IDecoderObj ectID to the type 
specified by iModel. 

0 KamDe c ode r Ge t MaxAddr e s s 

Parameter List Type Range Direction Description 
2 0 iModel int 1 In Decoder type ID 

piMaxAddress int * 2 Out Maximum decoder 

address 

1 Maximum value for this server given by 
KamDecoderGetMaxModels . 

2 5 2 Model dependent. 0 returned on error. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

3 0 KamDe code rGe t MaxAddr e s s takes a decoder type ID and a 

pointer to store the maximum address as parameters. It 
sets the memory pointed to by piMaxAddress to the maximum 
address supported by the specified decoder. 

3 5 OKamDecoderChangeOldNewAddr 

Parameter List Type Range Direction Description 
lOldObjID long 1 In Old decoder object ID 

iNewAddr int 2 In New decoder address 

plNewObjlD long * 1 Out New decoder object ID 

.4 0 1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 1-12 7 for short locomotive addresses. 1-1023 9 for 
long locomotive decoders. 0-511 for accessory decoders. 
Return Value Type Range Description 

45 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamDecoderChangeOldNewAddr takes an old decoder object ID 4 
and a new decoder address as parameters. It moves the 
50 specified locomotive or accessory decoder to iNewAddr and 
sets the memory pointed to by plNewObjlD to the new 
object ID. The old object ID is now invalid and should 
no longer be used. 



0 KamDe coderMove Port 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 
iLogicalPortID int 1-65535 2 In Logical port ID 
5 1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

Return Value Type Range Description 

10 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamDecoderMovePort takes a decoder object ID and logical 
port ID as parameters. It moves the decoder specified by 
15 lDecoderObjectlD to the controller specified by 
iLogi calPortID . 

OKamDecoderGetPort 

Parameter List Type Range Direction Description 
2 0 lDecoderObjectlD long 1 In Decoder object ID 

piLogicalPortID int * 1-65535 2 Out Pointer to 

logical port ID 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 5 2 Maximum value for this server given by 

KamPortGetMaxLogPorts . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

3 0 (see KamMiscGetErrorMsg) . 

KamDecoderMovePort takes a decoder object ID and pointer 
to a logical port ID as parameters. It sets the memory 
pointed to by piLogicalPortID to the logical port ID 
associated with lDecoderObjectlD. 

35 

OKamDecoderCheckAddrlnUse 

Parameter List Type Range Direction Description 
iDecoderAddress int 1 In Decoder address 

iLogicalPortID int 2 In Logical Port ID 

4 0 iDecbderClass int 3 In Class of decoder 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

4 5 3 1 - DECODER_ENGINE_TYPE , 

2 - DECODER_SWITCH_TYPE, 

3 - DECODER_SENSOR_TYPE . 

Return Value Type Range Description 

iError short 1 Error flag 

50 1 iError = 0 for successful call and address not in 
use. Nonzero is an error number (see 

KamMiscGetErrorMsg) . I D S_ERR_ADDRE S S EX 1ST returned if 
call succeeded but the address exists. 
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KamDecoderCheckAddrlnUse takes a decoder address, logical 
port, and decoder class as parameters. It returns zero 
if the address is not in use. It will return 
IDS_ERR_ADDRESSEXIST if the call succeeds but the address 
5 already exists. It will return the appropriate non zero 
error number if the calls fails. 

OKamDecoderGetModelFromObj 

Parameter List Type Range Direction Description 
10 iDecoderObjectID long 1 In Decoder object ID 

piModelint * 1-65535 2 Out Pointer to decoder 

type ID 

1 Opaque object ID handle returned by 
KamDe coder Put Add . 
15 2 Maximum value for this server given by 
KamDecoderGetMaxModels . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

2 0 (see KamMiscGetErrorMsg) . 

KamDecoderGetModelFromObj takes a decoder object ID and 
pointer to a decoder type ID as parameters. It sets the 
memory pointed to by piModel to the decoder type ID 
associated with iDCCAddr. 

25 

OKamDecoderGetModel Facility 

Parameter List Type Range Direction Description 
IDecoderObjectID long 1 In Decoder object ID 

pdwFacility long * 2 Out Pointer to decoder 

30 facility mask 

1 Opaque object ID handle returned by 
KamDecoderPut Add . 

2 0 - DCODE_PRGMODE_ADDR 

I - DCODE_PRGMODE_REG 

3 5 2 - DCODE__PRGMODE__PAGE 

3 - DCODE_PRGMODE_D I R 

4 - DCODE_PRGMODE__FLYSHT 

5 - DCODE_PRGMODE_FLYLNG 

6 - Reserved 

4 0 7 - Reserved 

8 - Reserved 

9 - Reserved 

10 - Reserved 

II - Reserved 
45 12 - Reserved 

13 - DCODE__FE AT_JD I RL I GHT 

14 - DCODE_FEAT_LNGADDR 

15 - DCODE_FEAT_CVENABLE 

16 - DCODE_FEDMODE__ADDR 
50 17 - DCODE_FEDMODE_REG 

18 - DCODE_FEDMODE_PAGE 

19 - DCODE_FEDMODE_DIR 

20 - DCODE_FEDMODE_FLYSHT 

21 - DCODE FEDMODE FLYLNG 
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Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
5 KamDecoderGetModelFacility takes a decoder object ID and 
pointer to a decoder facility mask as parameters. It 
sets the memory pointed to by pdwFacility to the decoder 
facility mask associated with iDCCAddr. 

10 0 KamDecoderGetObj Count 

Parameter List Type Range Direction Description 
iDecoderClass int 1 In Class of decoder 

piObj Count int * 0-6553 5 Out Count of active 

decode rs 

15 1 1 - DECODER_ENGINE_TYPE, 

2 - DECODER_SWITCH_TYPE, 

3 - DECODER_SENSOR__TYPE . 

Return Value Type Range Description* 

iError short 1 Error flag 

2 0 1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamDecoderGetObj Count takes a decoder class and a pointer 
to an address count as parameters. It sets the memory 
pointed to by piObjCount to the count of active decoders 

2 5 of the type given by iDecoderClass. 

0 KamDe coderGe t Ob j At I ndex 

Parameter List Type Range Direction Description* 
i Index int 1 In Decoder array index 

30 iDecoderClass int 2 In Class of decoder 

pIDecoderObjectID long * 3 Out Pointer to decoder 

object ID 

1 0 to (KamDecoderGetAddressCount - 1) . 

2 1 - DECODER__ENGINE_TYPE, 

3 5 2 - DECODER_SWITCH_TYPE, 

3 - DECODER_SENSOR_TYPE . 

3 Opaque object ID handle returned by 
KamDecoderPutAdd . 

Return Value Type Range Description 

4 0 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamDecoderGetObj Count takes a decoder index, decoder 
class, and a pointer to an object ID as parameters. It 
45 sets the memory pointed to by pIDecoderObjectID to the 
selected object ID. 

0 KamDecoderPutAdd 

Parameter List Type Range Direction Description 
50 iDecoderAddress int 1 In Decoder address 

iLogicalCmdPortID int 1-65535 2 In Logical 

command 
port ID 
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iLogicalProgPortID int 1-65535 2 In Logical 

programming 
port ID 

iClearState int 3 In Clear state flag 

5 iModel int 4 In Decoder model type ID 

plDecoderObjectlD long * 5 Out Decoder 

object ID 

1 1-127 for short locomotive addresses. 1-10239 for 
long locomotive decoders. 0-511 for accessory decoders. 
10 2 Maximum value for this server given by 
KamPor t Ge tMaxLogPor t s . 

3 0 - retain state, 1 - clear state. 

4 Maximum value for this server given by 
KamDecoderGetMaxModels . 

15 5 Opaque object ID handle. The object ID is used to 
reference the decoder. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
2 0 (see KamMiscGetErrorMsg) . 

KamDe coder Put Add takes a decoder object ID, command 
logical port, programming logical port, clear flag, 
decoder model ID, and a pointer to a decoder object ID as 
parameters. It creates a new locomotive object in the 

2 5 locomotive database and sets the memory pointed to by 

plDecoderObjectlD to the decoder object ID used by the 
server as a key. 

• OKamDecoderPutDel 

3 0 Parameter List Type Range Direction Description 

lDecoderObjectlD long 1 In Decoder object ID 

iClearState int 2 In Clear state flag 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 
35 2 0 - retain state, 1 - clear state. 

Return Value Type Range Description* 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

4 0 KamDecoderPutDel takes a decoder object ID and clear flag 

as parameters. It deletes the locomotive object specified 
by lDecoderObjectlD from the locomotive database. 

OKamDecoderGetMf gName 
45 Parameter List Type Range Direction Description 

lDecoderObjectlD long 1 In Decoder object ID 

pbsMfgName BSTR * 2 Out Pointer to 

manufacturer name 

1 Opaque object ID handle returned by 

5 0 KamDecoderPutAdd . 

2 Exact return type depends on language. It is 
Cstring * for C++. Empty string on error. 
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Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
5 KamDecoderGetMfgName takes a decoder object ID and 

pointer to a manufacturer name string as parameters. It 
sets the memory pointed to by pbsMfgName to the name of 
the decoder manufacturer. 

10 OKamDecoderGetPowerMode 

Parameter List Type Range Direction Description 
iDecoderObjectID long 1 In Decoder object ID 

pbsPowerMode BSTR * 2 Out Pointer to 

decoder power 

15 mode 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Exact return type depends on language . It is 
Cstring * for C++. Empty string on error. 

2 0 Return Value Type Range Description* 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamDecoderGetPowerMode takes a decoder object ID and a 
25 pointer to the power mode string as parameters. It sets 
the memory pointed to by pbsPowerMode to the decoder 
power mode . 

OKamDecoderGetMaxSpeed 

3 0 Parameter List Type Range Direction Description 

iDecoderObj ectID long 1 In Decoder obj ect ID 

piSpeedStep int * 2 Out Pointer to max 

speed step 

1 Opaque object ID handle returned by 

3 5 KamDecoderPutAdd . 

2 14, 28, 56, or 128 for locomotive decoders. 0 for 
accessory decoders. 

Return Value Type Range Description 

iError short 1 Error flag 

40 1 iError = 0 for success. Nonzero is an error number 

(see KamMiscGetErrorMsg) . 

KamDecoderGetMaxSpeed takes a decoder object ID and a 
pointer to the maximum supported speed step as 
parameters. It sets the memory pointed to by piSpeedStep 

4 5 to the maximum speed step supported by the decoder. 



A. Commands to control locomotive decoders 

50 This section describes the commands that 

control locomotive decoders. These commands control 
things such as locomotive speed and direction. For 
efficiency, a copy of all the engine variables such speed 
is stored in the server. Commands such as KamEngGetSpeed 



communicate only with the server, not the actual decoder. 
You should first make any changes to the server copy of 
the engine variables. You can send all changes to the 
engine using the KamCmdCommand command. 

5 

OKamEngGet Speed 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

IpSpeed int * 2 Out Pointer to locomotive 

10 speed 

lpDirection int * 3 Out Pointer to locomotive 

direction 

1 Opaque object ID handle returned by 
KamDecoderPut Add . 
15 2 Speed range is dependent on whether the decoder is 
set to 14,18, or 128 speed steps and matches the values 
defined by NMRA S9.2 and RP 9.2.1. 0 is stop and 1 is 
emergency stop for all modes. 

3 Forward is boolean TRUE and reverse is boolean 
2 0 FALSE. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
2 5 KamEngGet Speed takes the decoder object ID and pointers 
to locations to store the locomotive speed and direction 
as parameters. It sets the memory pointed to by IpSpeed 
to the locomotive speed and the memory pointed to by 
lpDirection to the locomotive direction. 

30 

0 KamEngPut Speed 

Parameter List Type Range Direction Description* 
lDecoderObjectlD long 1 In Decoder object ID 

iSpeed int 2 In Locomotive speed 

35 iDirection int 3 In Locomotive direction 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Speed range is dependent on whether the decoder is 
set to 14,18, or 128 speed steps and matches the values 

40 defined by NMRA S9.2 and RP 9.2.1, 0 is stop and 1 is 
emergency stop for all modes. 

3 Forward is boolean TRUE and reverse is boolean 
FALSE . 

Return Value Type Range Description 

45 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamEngPut Speed takes the decoder object ID, new 
locomotive speed, and new locomotive direction as 
50 parameters. It sets the locomotive database speed to 
iSpeed and the locomotive database direction to 
iDirection. Note: This command only changes the 
locomotive database. The data is not sent to the decoder 
until execution of the KamCmdCommand command. Speed is 
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set to the maximum possible for the decoder if iSpeed 
exceeds the decoders range . 

OKamEngGet Speeds teps 
5 Parameter List Type Range Direction Description 

lDecoderObjectlD long 1 In Decoder object ID 

IpSpeedSteps int * 14,28,128 Out Pointer to number 

of speed steps 

1 Opaque object ID handle returned by 
10 KamDecoderPutAdd. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
15 KamEngGetSpeedSteps takes the decoder object ID and a 

pointer to a location to store the number of speed steps 
as a parameter. It sets the memory pointed to by 
IpSpeedSteps to the number of speed steps . 

2 0 OKamEngPutSpeedSteps 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

iSpeedSteps int 14,28,128 In Locomotive speed 

steps 

2 5 1 Opaque object ID handle returned by 

KamDecoderPutAdd . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

3 0 (see KamMiscGetErrorMsg) . 

KamEngPutSpeedSteps takes the decoder object ID and a new 
number of speed steps as a parameter. It sets the number 
of speed steps in the locomotive database to iSpeedSteps . 
Note: This command only changes the locomotive database. 
3 5 The data is not sent to the decoder until execution of 

the KamCmdCommand command. KamDecoderGetMaxSpeed returns 
the maximum possible speed for the decoder. An error is 
generated if an attempt is made to set the speed steps 
beyond this value. 

40 

0 KamEngGe t Func t i on 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

iFunctionID int 0-8 2 In Function ID number 
45 lpFunction int * 3 Out Pointer to function 

value 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 FL is 0. F1-F8 are 1-8 respectively. Maximum for 
5 0 this decoder is given by KamEngGe t Func t i onMax . 3 

Function active is boolean TRUE and inactive is boolean 
FALSE . 
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Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

5 KamEngGet Function takes the decoder object ID, a function 
ID, and a pointer to the location to store the specified 
function state as parameters. It sets the memory pointed 
to by lpFunction to the specified function state. 

10 0 KamEng Pu t Func t i on 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

iFunctionID int 0-8 2 In Function ID number 
iFunction int 3 In Function value 

15 1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 FL is 0. F1-F8 are 1-8 respectively. Maximum for 
this decoder is given by KamEngGet Func t ionMax . 

3 Function active is boolean TRUE and inactive is 
2 0 boolean FALSE. 

Return Value Type Range Description* 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

2 5 KamEngPut Function takes the decoder object ID, a function 

ID, and a new function state as parameters. It sets the 
specified locomotive database function state to 
iFunction. Note: This command only changes the 
locomotive database. The data is not sent to the decoder 
30 until execution of the KamCmdCommand command. 

0 KamEngGe t Func t i onMax 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

3 5 piMaxFunction int * 0-8 Out Pointer to maximum 

function number 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

Return Value Type Range Description 

4 0 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamEngGet Funct ionMax takes a decoder object ID and a 
pointer to the maximum function ID as parameters. It 
4 5 sets the memory pointed to by piMaxFunction to the 
maximum possible function number for the specified 
decoder . 
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OKamEngGetName 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

pbsEngName BSTR * 2 Out Pointer to 

5 locomotive name 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Exact return type depends on language. It is 
Cstring * for C++. Empty string on error. 

10 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamEngGetName takes a decoder object ID and a pointer to 
15 the locomotive name as parameters. It sets the memory 
pointed to by pbsEngName to the name of the locomotive. 

OKamEngPutName 

Parameter List Type Range Direction Description* 

2 0 lDecoderObjectlD long 1 In Decoder object ID 

bsEngName BSTR 2 Out Locomotive name 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Exact parameter type depends on language. It is 
25 LPCSTR for C++. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

3 0 KamEngPutName takes a decoder object ID and a BSTR as 

parameters. It sets the symbolic locomotive name to 
bsEngName . 

0 KamEngGe t Func t i onName 

3 5 Parameter List Type Range Direction Description 

lDecoderObjectlD long 1 In Decoder object ID 

iFunctionID int 0-8 2 In Function ID number 
pbsFcnNameString BSTR * 3 Out Pointer to 

function name 

4 0 1 Opaque object ID handle returned by 

KamDecoderPutAdd . 

2 FL is 0. F1-F8 are 1-8 respectively. Maximum for 
this decoder is given by KamEngGe t Func t i onMax . 3 Exact 
return type depends on language. It is Cstring * for 

45 C++. Empty string on error. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError* = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

5 0 KamEngGetFuncntionName takes a decoder object ID, 

function ID, and a pointer to the function name as 
parameters. It sets the memory pointed to by 
pbsFcnNameString to the symbolic name of the specified 
function . 
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0 KamEng Pu t Func t i onName 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

iFunctionID int 0-8 2 In Function ID number 
5 bsFcnNameString BSTR 3 In Function name 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 FL is 0. F1-F8 are 1-8 respectively. Maximum for 
this decoder is given by KamEngGetFunctionMax . 

10 3 Exact parameter type depends on language. It is 
LPCSTR for C++. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
15 (see KamMiscGetErrorMsg) . 

KamEngPutFunctionName takes a decoder object ID, function 
ID, and a BSTR as parameters. It sets the specified 
symbolic function name to bsFcnNameString. 

2 0 OKamEngGetConsistMax 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

piMaxConsist int * 2 Out Pointer to max consist 

number 

25 1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Command station dependent. 

Return Value Type Range Description 

iError short 1 Error flag 

30 1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamEngGe t Cons i s t Max takes the decoder object ID and a 
pointer to a location to store the maximum consist as 
parameters. It sets the location pointed to by 

3 5 piMaxConsist to the maximum number of locomotives that 

can but placed in a command station controlled consist. 
Note that this command is designed for command station 
consisting. CV consisting is handled using the CV 
commands . 

4 0 

0 KamEngPut Cons i s t Parent 

Parameter List Type Range Direction Description 
lDCCParentObj ID long 1 In Parent decoder 

object ID 

4 5 iDCCAliasAddr int 2 In Alias decoder address 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 1-127 for short locomotive addresses. 1-10239 for 
long locomotive decoders. 

50 Return Value Type Range Description 

iError short 1 Error flag 

1 iError - 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamEngPut Cons i st Parent takes the parent object ID and an 
55 alias address as parameters. It makes the decoder 
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specified by iDCCParentObj ID the consist parent referred 
to by iDCCAliasAddr . Note that this command is designed 
for command station consisting. CV consisting is handled 
using the CV commands. If a new parent is defined for a 
5 consist; the old parent becomes a child in the consist. 
To delete a parent in a consist without deleting the 
consist, you must add a new parent then delete the old 
parent using KamEngPutConsistRemoveObj . 

10 OKamEngPutConsistChild 

Parameter List Type Range Direction Description 
IDCCParentObj ID long 1 In Parent decoder 

object ID 

iDCCObjID long 1 in Decoder object ID 

15 1 Opaque object ID handle returned by 
KamDecoderPut Add . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

20 (see KamMiscGetErrorMsg) . 

KamEngPutConsistChild takes the decoder parent object ID 
and decoder object ID as parameters. It assigns the 
decoder specified by IDCCObjID to the consist identified 
by IDCCParentObj ID. Note that this command is designed 

25 for command station consisting. CV consisting is handled 
using the CV commands. Note: This command is invalid if 
the parent has not been set previously using 
KamEngPutConsistParent . 

3 0 0 KamEngPutCons i s tRemoveOb j 

Parameter List Type Range Direction Description 

lDecoderObjectlD long 1 In Decoder object ID 

1 Opaque object ID handle returned by 

KamDecoderPutAdd . 
3 5 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamEngPutConsistRemoveObj takes the decoder object ID as 
40 a parameter. It removes the decoder specified by 
iDecoderOJbjectJD from the consist. Note that this 
command is designed for command station consisting. CV 
consisting is handled using the CV commands. Note: If 
the parent is removed, all children are removed also. 

45 

A. Commands to control accessory decoders 

This section describes the commands that 
50 control accessory decoders. These commands control 

things such as accessory decoder activation state. For 
efficiency, a copy of all the engine variables such speed 
is stored in the server. Commands such as 
KamAccGet Function communicate only with the server, not 
55 the actual decoder. You should first make any changes to 
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the server copy of the engine variables. You can send 
all changes to the engine using the KamCmdCommand 
command . 

5 0 KamAc c Get Func t i on 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

iFunctionID int 0-31 2 In Function ID number 
lpFunction int * 3 Out Pointer to function 

10 value 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum for this decoder is given by 
KamAccGetFunctionMax . 

15 3 Function active is boolean TRUE and inactive is 
boolean FALSE. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

2 0 (see KamMiscGetErrorMsg) . 

KamAccGetFunction takes the decoder object ID, a function 
ID, and a pointer to the location to store the specified 
function state as parameters. It sets the memory pointed 
to by lpFunction to the specified function state. 

25 

0 KamAc c Ge t Func t i onAl 1 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

piValue int * 2 Out Function bit mask 

3 0 1 Opaque object ID handle returned by 

KamDecoderPutAdd . 

2 Each bit represents a single function state. 
Maximum for this decoder is given by 
KamAccGetFunctionMax . 

3 5 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamAccGetFunctionAll takes the decoder object ID and a 
40 pointer to a bit mask as parameters. It sets each bit in 
the memory pointed to by piValue to the corresponding 
function state. 

0 KamAc c Pu t Func t i on 

45 Parameter List Type Range Direction Description 

lDecoderObjectlD long 1 In Decoder object ID 

iFunctionID int 0-31 2 In Function ID number 
iFunction int 3 In Function value 

1 Opaque object ID handle returned by 
5 0 KamDecoderPutAdd . 

2 Maximum for this decoder is given by 
KamAccGetFunctionMax . 

3 Function active is boolean TRUE and inactive is 
boolean FALSE. 
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Return Value Type Range Description* 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
5 KamAccPutFunction takes the decoder object ID, a function 
ID, and a new function state as parameters. It sets the 
specified accessory database function state to iFunction. 
Note: This command only changes the accessory database. 
The data is not sent to the decoder until execution of 
10 the KamCmdCommand command. 

0 KamAc c Put Func t i onAl 1 

Parameter List Type Range Direction Description 
IDecoderObj ect ID long 1 In Decoder object ID 

15 iValue int 2 In Pointer to function state 

array 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Each bit represents a single function state. 
2 0 Maximum for this decoder is given by 

KamAc c Ge t Func t i onMax . 

Return Value Type Range Description* 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

2 5 (see KamMiscGetErrorMsg) . 

KamAc c Put Func tionAll takes the decoder object ID and a 
bit mask as parameters. It sets all decoder function 
enable states to match the state bits in i Value . The 
possible enable states are TRUE and FALSE. The data is 

3 0 not sent to the decoder until execution of the 

KamCmdCommand command . 

0 KamAc c Ge t Func t i onMax 

Parameter List Type Range Direction Description 

3 5 IDecoderObj ect ID long 1 In Decoder object ID 

piMaxFunction int * 0-31 2 Out Pointer to maximum 

function number 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

4 0 2 Maximum for this decoder is given by 

KamAc cGe t Func t i onMax . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

45 (see KamMiscGetErrorMsg) . 

KamAccGetFunctionMax takes a decoder object ID and 
pointer to the maximum function number as parameters. It 
sets the memory pointed to by piMaxFunction to the 
maximum possible function number for the specified 

50 decoder. 

0 KamAc c Ge t Name 

Parameter List Type Range Direction Description 

IDecoderObj ect ID long 1 In Decoder object ID 

55 pbsAccNameString BSTR * 2 Out Accessory name 



1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Exact return type depends on language. It is 
Cstring * for C++. Empty string on error. 

5 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamAccGetName takes a decoder object ID and a pointer to 
10 a string as parameters. It sets the memory pointed to by 
pbsAccNameString to the name of the accessory. 

OKamAccPutName 

Parameter List Type Range Direction Description 
15 IDecoderObj ectID long 1 In Decoder object ID 

bsAccNameString BSTR 2 In Accessory name 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Exact parameter type depends on language. It is 
2 0 LPCSTR for C++. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

2 5 KamAccPutName takes a decoder object ID and a BSTR as 

parameters. It sets the symbolic accessory name to 
bsAccName . 

0 KamAc c Ge t Func t i onName 

3 0 Parameter List Type Range Direction Description 

IDecoderObj ect ID long 1 In Decoder object ID 

iFunctionID int 0-31 2 In Function ID number 
pbsFcnNameString BSTR * 3 Out Pointer to 

function name 

3 5 1 Opaque object ID handle returned by 

KamDecoderPutAdd . 

2 Maximum for this decoder is given by 
KamAc cGe t Func t i onMax . 

3 Exact return type depends on language. It is 

4 0 Cstring * for C++. Empty string on error. 

Return Value Type Range Description* 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

4 5 KarnAccGetFuncntionName takes a decoder object ID, 

function ID, and a pointer to a string as parameters. It 
sets the memory pointed to by pbsFcnNameString to the 
symbolic name of the specified function. 

50 0 KamAc c Put Func t i onName 

Parameter List Type Range Direction Description 

IDecoderObj ect ID long 1 In Decoder object ID 

iFunctionID int 0-31 2 In Function ID number 

bsFcnNameString BSTR 3 In Function name 



1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum for this decoder is given by 
KamAc c Ge t Func t i onMax . 

5 3 Exact parameter type depends on language. It is 
LPCSTR for C++. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
10 (see KamMiscGetErrorMsg) . 

KamAc c Put Func tionName takes a decoder object ID, function 
ID, and a BSTR as parameters. It sets the specified 
symbolic function name to bsFcnNameString . 

1 5 OKamAccRegFeedback 

Parameter List Type Range Direction Description* 
lDecoderObjectlD long 1 In Decoder object ID 

bsAccNode BSTR 1 In Server node name 

iFunctionID int 0-31 3 In Function ID number 

2 0 1 Opaque object ID handle returned by 
KamDecoderPutAdd. 

2 Exact parameter type depends on language. It is 
LPCSTR for C++. 

3 Maximum for this decoder is given by 

2 5 KamAccGetFunctionMax. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError* = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

3 0 KamAccRegFeedback takes a decoder object ID, node name 

string, and function ID, as parameters. It registers 
interest in the function given by iFunctionID by the 
method given by the node name string bsAccNode. 
bsAccNode identifies the server application and method to 
35 call if the function changes state. Its format is 

"\\ {Server) \ {App} . {Method} " where {Server} is the server 
name, {App) is the application name, and {Method} is the 
method name . 

4 0 OKamAccRegFeedbackAll 

Parameter List Type Range Direction Description 
lDecoderObjectlD long 1 In Decoder object ID 

bsAccNode BSTR 2 In Server node name 

1 Opaque object ID handle returned by 
4 5 KamDecoderPutAdd. 

2 Exact parameter type depends on language. It is 
LPCSTR for C++. 

Return Value Type Range Description 

iError short 1 Error flag 

50 1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamAccRegFeedbackAll takes a decoder object ID and node 
name string as parameters. It registers interest in all 
functions by the method given by the node name string 



51 

bsAccNode. bsAccNode identifies the server application 
and method to call if the function changes state. Its 
format is M \\{Server}\{App} . {Method} " where {Server} is 
the server name, {App} is the application name, and 
5 {Method} is the method name. 

OKamAccDel Feedback 

Parameter List Type Range Direction Description 
IDecoderObj ectID long 1 In Decoder object ID 

10 bsAccNode BSTR 2 In Server node name 

iFunctionID int 0-31 3 In Function ID number 

1 Opaque object ID handle returned by 
KamDecoderPut Add . 

2 Exact parameter type depends on language. It is 
15 LPCSTR for C++. 

3 Maximum for this decoder is given by 
KamAccGe t Func t i onMax . 

Return Value Type Range Description 

iError short 1 Error flag 

20 1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamAccDel Feedback takes a decoder object ID, node name 
string, and function ID, as parameters. It deletes 
interest in the function given by iFunctionID by the 

2 5 method given by the node name string bsAccNode. 

bsAccNode identifies the server application and method to 
call if the function changes state. Its format is 
11 \\ {Server) \ {App} . {Method} " where {Server} is the server 
name, {App} is the application name, and {Method} is the 

3 0 method name . 

0 KamAc cDe 1 FeedbackAl 1 

Parameter List Type Range Direction Description* 
IDecoderObj ect ID long 1 In Decoder object ID 

3 5 bsAccNode BSTR 2 In Server node name 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Exact parameter type depends on language. It is 
LPCSTR for C++. 

4 0 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamAccDelFeedbackAll takes a decoder object ID and node 
45 name string as parameters. It deletes interest in all 
functions by the method given by the node name string 
bsAccNode. bsAccNode identifies the server application 
and method to call if the function changes state. Its 
format is ,! \\ {Server } \ {App} . {Method} " where {Server} is 
50 the server name, {App} is the application name, and 
{Method} is the method name. 
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A. Commands to control the command station 

This section describes the commands that 
control the command station. These commands do things 
5 such as controlling command station power. The steps to 
control a given command station vary depending on the 
type of command station. 

0 KamOpr Put TurnOnS t a t i on 

10 Parameter List Type Range Direction Description 

iLogicalPortID int 1-65535 1 In Logical port ID 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

Return Value Type Range Description 

15 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamOprPutTurnOnStation takes a logical port ID as a 
parameter. It performs the steps necessary to turn on 
20 the command station. This command performs a combination 
of other commands such as KamOprPutStartStat ion, 
KamOprPutClearStation, and KamOpr Put PowerOn . 

OKamOprPut Start Stat ion 
25 Parameter List Type Range Direction Description 

iLogicalPortID int 1-65535 1 In Logical port ID 
1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

Return Value Type Range Description 

3 0 iError short 1 Error flag 

1 iError = 0 for success . Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamOprPutStartStation takes a logical port ID as a 
parameter. It performs the steps necessary to start the 

3 5 command station. 

OKamOprPutClearStation 

Parameter List Type Range Direction Description 
iLogicalPortID int 1-65535 1 In Logical port ID 

4 0 1 Maximum value for this server given by 

KamPortGetMaxLogPorts . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
45 (see KamMiscGetErrorMsg) . 

KamOprPutClearStation takes a logical port ID as a 
parameter. It performs the steps necessary to clear the 
command station queue. 

5 0 OKamOprPut StopSt at ion 

Parameter List Type Range Direction Description 
iLogicalPortID int 1-65535 1 In Logical port ID 
1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 



Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
5 KamOprPutStopStation takes a logical port ID as a 

parameter. It performs the steps necessary to stop the 
command station. 

0 KamOpr Put Powe rOn 

10 Parameter List Type Range Direction Description 

iLogicalPortID int 1-65535 1 In Logical port ID 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

Return Value Type Range Description 

15 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamOpr Put Powe rOn takes a logical port ID as a parameter. 
It performs the steps necessary to apply power to the 
2 0 track. 

0 KamOp r P u t P owe r 0 f f 

Parameter List Type Range Direction Description 
iLogicalPortID int 1-65535 1 In Logical port ID 

2 5 1 Maximum value for this server given by 

KamPortGetMaxLogPorts . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success . Nonzero is an error number 

3 0 (see KamMiscGetErrorMsg) . 

KamOprPutPowerOf f takes a logical port ID as a parameter. 
It performs the steps necessary to remove power from the 
track . 

3 5 OKamOprPutHardReset 

Parameter List Type Range Direction Description 
iLogicalPortID int 1-65535 1 In Logical port ID 
1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

4 0 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamOprPutHardReset takes a logical port ID as a 
4 5 parameter. It performs the steps necessary to perform a 
hard reset of the command station. 

0 KamOp r Pu t Erne r g e ncy S t op 

Parameter List Type Range Direction Description 
50 iLogicalPortID int 1-65535 1 In Logical port ID 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

Return Value Type Range Description 

iError short 1 Error flag 
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1 iError - 0 for success. Nonzero is an error number 
(see KainMiscGetErrorMsg) . 

KamOprPutEmergencyStop takes a logical port ID as a 
parameter. It performs the steps necessary to broadcast 
5 an emergency stop command to all decoders. 

OKamOprGetStationStatus 

Parameter List Type Range Direction Description 
iLogicalPortID int 1-65535 1 In Logical port ID 
10 pbsCmdStat BSTR * 2 Out Command station status 

string 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

2 Exact return type depends on language. It is 
15 Cstring * for C++. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
2 0 KamOprGetStationStatus takes a logical port ID and a 
pointer to a string as parameters. It set the memory 
pointed to by pbsCmdStat to the command station status. 
The exact format of the status BSTR is vendor dependent . 



A . Commands to configure the command station 
communication port 

This section describes the commands that 
30 configure the command station communication port. These 
commands do things such as setting BAUD rate. Several of 
the commands in this section use the numeric controller 
ID (iControllerlD) to identify a specific type of 
command station controller . The following table shows 
3 5 the mapping between the controller ID (iControllerlD) and 
controller name (bsControllerName) for a given type of 
command station controller. 



iControllerlD bsControllerName Description 



40 


0 


UNKNOWN 


Unknown controller type 




1 


SIMULAT 


Interface simulator 




2 


LENZ lx 


Lenz version 1 serial support module 




3 


LENZ 2x 


Lenz version 2 serial support module 




4 


DIGIT_DT200 


Digitrax direct drive support using 
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DT200 




5 


DIGIT_DCS100 


Digitrax direct drive support using 
DCS100 




6 


MASTERSERIES 


North coast engineering master 
series 
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7 


SYSTEMONE 


System one 




8 


RAMFIX 


RAMFIxx system 




9 


SERIAL 


NMRA serial interface 




10 


EASYDCC 


CVP Easy DCC 




11 


MRK6050 


Marklin 6050 interface (AC and DC) 
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12 


MRK602 3 


Marklin 6023 -interface (AC) 
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13 DIGIT_PR1 Digitrax direct drive using PR1 

14 DIRECT Direct drive interface routine 

15 ZTC ZTC system ltd 

16 TRIX TRIX controller 

5 

ilndex Name iValue Values 

0 RETRANS 10-2 55 

1 RATE 0 - 300 BAUD, 1 - 1200 BAUD, 2 - 2400 BAUD, 

3 - 4800 BAUD, 4 - 9600 BAUD, 5 - 14400 BAUD, 
10 6 - 16400 BAUD, 7 - 19200 BAUD 

2 PARITYO - NONE, 1 - ODD, 2 - EVEN, 3 - MARK, 

4 - SPACE 

3 STOP 0-1 bit, 1 - 1.5 bits, 2-2 bits 

4 WATCHDOG 500 - 65535 milliseconds. Recommended 
15 value 2048 

5 FLOW 0 - NONE, 1 - XON/XOFF , 2 - RTS/CTS, 3 BOTH 

6 DATA 0-7 bits, 1-8 bits 

7 DEBUGBit mask. Bit 1 sends messages to debug file. 
Bit 2 sends messages to the screen. Bit 3 shows 

20 queue data. Bit 4 shows UI status. Bit 5 is 

reserved. Bit 6 shows semaphore and critical 
sections. Bit 7 shows miscellaneous messages. Bit 
8 shows comm port activity. 13 0 decimal is 
recommended for debugging. 

2 5 8 PARALLEL 

OKamPortPutConf ig 

Parameter List Type Range Direction Description* 
iLogicalPortID int 1-65535 1 In Logical port ID 

3 0 ilndex int 2 In Configuration type index 

iValue int 2 In Configuration value 

iKey int 3 In Debug key 

1 Maximum value for this server given by 
KamPor t Ge t MaxLogPor t s . 
35 2 See Figure 7: Controller configuration Index values 
for a table of indexes and values. 

3 Used only for the DEBUG ilndex value. Should be set 
to 0 . 

Return Value Type Range Description 

4 0 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamPortPutConf ig takes a logical port ID, configuration 
index, configuration value, and key as parameters. It 
45 sets the port parameter specified by i Index to the value 
specified by iValue. For the DEBUG ilndex value, the 
debug file path is C : \Temp\Debug{PORT} . txt where {PORT} 
is the physical comm port ID. 

50 OKamPortGetConf ig 

Parameter List Type Range Direction Description 

iLogicalPortID int 1-65535 1 In Logical port ID 

ilndex int 2 In Configuration type index 

piValue int * 2 Out Pointer to configuration value 



1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

2 See Figure 7: Controller configuration Index values 
for a table of indexes and values. 

5 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

10 KamPortGetConf ig takes a logical port ID, configuration 
index, and a pointer to a configuration value as 
parameters. It sets the memory pointed to by piValue to 
the specified configuration value. 

15 OKamPortGetName 

Parameter List Type Range Direction Description 
iPhysicalPortID int 1-65535 1 In Physical port 

number 

pbsPortName BSTR * 2 Out Physical port name 

2 0 1 Maximum value for this server given by 
KamPortGetMaxPhysical . 

2 Exact return type depends on language. It is 
Cstring * for C++. Empty string on error. 

Return Value Type Range Description 

2 5 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamPortGetName takes a physical port ID number and a 
pointer to a port name string as parameters. It sets the 

3 0 memory pointed to by pbsPortName to the physical port 

name such as "COMMl." 

0 KamPort PutMapCont rol ler 



Parameter List 


Type 


Range 


Direction 


Description 


iLogicalPortID 


int 


1-65535 


1 


In 


Logical port ID 


i Control ler ID 


int 


1-65535 


2 


In 


Command station 
type ID 


iCommPortID 


int 


1-65535 


3 


In 


Physical comm 
port ID 



4 0 1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

2 See Figure 6: Controller ID to controller name 
mapping for values. Maximum value for this server is 
given by KamMiscMaxControllerlD. 
45 3 Maximum value for this server given by 
KamPortGetMaxPhysical . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
50 (see KamMiscGetErrorMsg) . 

KamPort PutMapCont roller takes a logical port ID, a 
command station type ID, and a physical communications 
port ID as parameters. It maps iLogicalPortID to 
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iCommPortID for the type of command station specified by 
i Con trol 1 erID . 

OKamPortGetMaxLogPorts 
5 Parameter List Type Range Direction Description* 
piMaxLogicalPorts int * 1 Out Maximum logical 

port ID 

1 Normally 1 - 65535. 0 returned on error. 
Return Value Type Range Description 

10 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamPortGetMaxLogPorts takes a pointer to a logical port 
ID as a parameter. It sets the memory pointed to by 
15 piMaxLogicalPorts to the maximum logical port ID. 

OKamPortGetMaxPhysical 

Parameter List Type Range Direction Description 
pMaxPhysical int * 1 Out Maximum physical 

20 port ID 

pMaxSerial int * 1 Out Maximum serial 

port ID 

pMaxParallel int * 1 Out Maximum parallel 

port ID 

25 1 Normally 1 - 65535. 0 returned on error. 
Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

3 0 KamPortGetMaxPhysical takes a pointer to the number of 

physical ports, the number of serial ports, and the 
number of parallel ports as parameters. It sets the 
memory pointed to by the parameters to the associated 
values 

35 

A. Commands that control command flow to the command 
station 

40 This section describes the commands that 

control the command flow to the command station. These 
commands do things such as connecting and disconnecting 
from the command station. 

4 5 0 KamCmdConne c t 

Parameter List Type Range Direction Description* 
iLogicalPortID int 1-65535 1 In Logical port ID 
1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 
50 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
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KamCmdConnect takes a logical port ID as a parameter. It 
connects the server to the specified command station. 

0 KamCmdD i s Conne c t 

5 Parameter List Type Range Direction Description 

iLogicalPortID int 1-65535 1 In Logical port ID 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

Return Value Type Range Description 

10 iError short ; 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamCmdD is Connect takes a logical port ID as a parameter. 
It disconnects the server to the specified command 
15 station. 

0 KamCmdCommand 

Parameter List Type Range Direction Description 
iDecoderObjectID long 1 In Decoder object ID 

2 0 1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
2 5 (see KamMiscGetErrorMsg) . 

KamCmdCommand takes the decoder object ID as a parameter. 
It sends all state changes from the server database to 
the specified locomotive or accessory decoder. 

30 

A. Cab Control Commands 

This section describes commands that control 
the cabs attached to a command station. 

35 

0 KamCabGe t Me s s age 

Parameter List Type Range Direction Description 
iCabAddress int 1-65535 1 In Cab address 

pbsMsg BSTR * 2 Out Cab message string 

40 1 Maximum value is command station dependent. 

2 Exact return type depends on language. It is 
Cstring * for C++. Empty string on error. 

Return Value Type Range Description 

iError short 1 Error flag 

45 1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamCabGetMessage takes a cab address and a pointer to a 
message string as parameters. It sets the memory pointed 
to by pbsMsg to the present cab message. 
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OKamCabPutMessage 

Parameter List Type Range Direction Description 
iCabAddress int 1 In Cab address 

bsMsg BSTR 2 Out Cab message string 

5 1 Maximum value is command station dependent. 

2 Exact parameter type depends on language. It is 
LPCSTR for C++. 

Return Value Type Range Description 

10 iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamCabPutMessage takes a cab address and a BSTR as 
parameters. It sets the cab message to bsMsg. 

15 

0 KamC abGe t C ab Add r 

Parameter List Type Range Direction Description* 
iDecoderObj ectID long 1 In Decoder object ID 

piCabAddress int * 1-65535 2 Out Pointer to Cab 

2 0 address 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum value is command station dependent. 
Return Value Type Range Descriptioni 

25 Error short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KarnCabGetCabAddr takes a decoder object ID and a pointer 
to a cab address as parameters. It set the memory 
30 pointed to by piCabAddress to the address of the cab 
attached to the specified decoder. 

0 KamCabPut AddrToCab 

Parameter List Type Range Direction Description 

3 5 IDecoderObj ect ID long 1 In Decoder object ID 

iCabAddress int 1-65535 2 In Cab address 

1 Opaque object ID handle returned by 
KamDecoderPutAdd . 

2 Maximum value is command station dependent. 

4 0 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamCabPutAddrToCab takes a decoder object ID and cab 
45 address as parameters. It attaches the decoder specified 
by iDCCAddr to the cab specified by iCabAddress . 
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A. Miscellaneous Commands 

This section describes miscellaneous commands 
that do not fit into the other categories. 

5 

0 KamMi s cGe t Er r orMsg 

Parameter List Type Range Direction Description 

iError int 0-65535 1 In Error flag 

1 iError = 0 for success. Nonzero indicates an error. 

10 Return Value Type Range Description 

bsErrorString BSTR 1 Error string 

1 Exact return type depends on language. It is 
Cstring for C++. Empty string on error. 
KamMi scGetErrorMsg takes an error flag as a parameter. 

15 It returns a BSTR containing the descriptive error 
message associated with the specified error flag. 

OKamMiscGetClockTime 

Parameter List Type Range Direction Description 
20 iLogicalPortID int 1-65535 1 In Logical port ID 

iSelectTimeMode int 2 In Clock source 

piDay int * 0-6 Out Day of week 

piHours int * 0-23 Out Hours 

piMinutes int * 0-59 Out Minutes 
25 piRatio int * 3 Out Fast clock ratio 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

2 0 - Load from command station and sync server. 

1 - Load direct from server. 2 - Load from cached server 
30 copy of command station time. 

3 Real time clock ratio. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

3 5 (see KamMiscGetErrorMsg) . 

KamMiscGetClockTime takes the port ID, the time mode, and 
pointers to locations to store the day, hours, minutes, 
and fast clock ratio as parameters. It sets the memory 
pointed to by piDay to the fast clock day, sets pointed 

4 0 to by piHours to the fast clock hours, sets the memory 

pointed to by piMinutes to the fast clock minutes, and 
the memory pointed to by piRatio to the fast clock ratio. 
The servers local time will be returned if the command 
station does not support a fast clock. 

45 

OKamMiscPutClockTime 

Parameter List Type Range Direction Description 
iLogicalPortID int 1-65535 1 In Logical port ID 
iDay int 0-6 In Day of week 

50 iHours int 0-23 In Hours 

iMinutes int 0-59 In Minutes 

iRatio int 2 In Fast clock ratio 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts. 2 Real time clock ratio. 

55 Return Value Type Range Description 
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iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamMiscPutClockTime takes the fast clock logical port, 
5 the fast clock day, the fast clock hours, the fast clock 
minutes, and the fast clock ratio as parameters. It sets 
the fast clock using specified parameters. 

OKamMiscGetlnterf aceVersion 
10 Parameter List Type Range Direction Description 

pbslnterf aceVersion BSTR * 1 Out Pointer to interface 

version string 

1 Exact return type depends on language. It is 

Cstring * for C++. Empty string on error. 
15 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamMiscGetlnterf aceVersion takes a pointer to an 
20 interface version string as a parameter. It sets the 

memory pointed to by pbslnterf aceVersion to the interface 
version string. The version string may contain multiple 
lines depending on the number of interfaces supported. 

25 OKamMiscSaveData 

Parameter List Type Range Direction Description 
NONE 

Return Value Type Range Description 

3 0 iError short 1 Error flag 

1 ■ iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamMiscSaveData takes no parameters. It saves all server 
data to permanent storage. This command is run 

3 5 automatically whenever the server stops running. Demo 

versions of the program cannot save data and this command 
will return an error in that case. 

OKamMiscGetControllerName 

4 0 Parameter List Type Range Direction Description 

iControllerlD int 1-65535 1 In Command station 

type ID 

pbsName BSTR * 2 Out Command station type 

name 

45 1 See Figure 6: Controller ID to controller name 

mapping for values. Maximum value for this server is 
given by KamMiscMaxControllerlD . 

2 Exact return type depends on language . It is 
Cstring * for C++. Empty string on error. 

50 Return Value Type Range Description 

bsName BSTR 1 Command station type name 
Return Value Type Range Description 

iError short 1 Error flag 

1 iError - 0 for success. Nonzero is an error number 
55 (see KamMiscGetErrorMsg) . 
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KamMiscGetControllerName takes a command station type ID 
and a pointer to a type name string as parameters. It 
sets the memory pointed to by pbsName to the command 
station type name. 

5 

OKamMiscGetControllerNameAtPort 

Parameter List Type Range Direction Description 
iLogicalPortID int 1-65535 1 In Logical port ID 
pbsName BSTR * 2 Out Command station type 

10 " name 

1 Maximum value for this server given by 
KamPortGetMaxLogPorts . 

2 Exact return type depends on language. It is 
Cstring * for C++. Empty string on error. 

15 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamMiscGetControllerName takes a logical port ID and a 
20 pointer to a command station type name as parameters. It 
sets the memory pointed to by pbsName to the command 
station type name for that logical port . 

OKamMiscGet Commands t at ionValue 
25 Parameter List Type Range Direction Description 

iControllerlD int 1-65535 1 In Command station 

type ID 

iLogicalPortID int 1-65535 2 In Logical port ID 
ilndex int 3 In Command station array index 

3 0 piValue int * 0 - 6 553 5 Out . Command station value 

1 See Figure 6: Controller ID to controller name 
mapping for values. Maximum value for this server is 
given by KamMiscMaxCont roller ID . 

2 Maximum value for this server given by 
35 KamPortGetMaxLogPorts . 

3 0 to KamMiscGetCommandStationlndex . 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 

4 0 (see KamMiscGetErrorMsg) . 

KamMiscGetCommandStat ionValue takes the controller ID, 
logical port, value array index, and a pointer to the 
location to store the selected value. It sets the memory 
pointed to by piValue to the specified command station 
45 miscellaneous data value. 
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OKamMiscSetCommandStationValue 

Parameter List Type Range Direction Description 
. iControllerlD int 1-65535 1 In Command station 

type ID 

5 iLogicalPortID int 1-65535 2 In Logical port ID 

i Index int 3 In Command station array index 

iValue int 0 - 6553 5 In Command station value 

1 See Figure 6: Controller ID to controller name 
mapping for values. Maximum value for this server is 

10 given by KamMiscMaxControllerlD . 

2 Maximum value for this server given by 
KamPortGetMaxLogPorts . 3 0 to 
KamMiscGetCommandStationlndex. 

15 Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamMiscSetCommandStationValue takes the controller ID, 
20 logical port, value array index, and new miscellaneous 
data value. It sets the specified command station data 
to the value given by piValue. 

OKamMiscGet Commands t at ionlndex 
25 Parameter List Type Range Direction Description 

iControllerlD int 1-65535 1 In Command station 

type ID 

iLogicalPortID int 1-65535 2 In Logical port ID 
pilndex int 0-65535 Out Pointer to maximum 

3 0 index 

1 See Figure 6: Controller ID to controller name 
mapping for values. Maximum value for this server is 
given by KamMiscMaxControllerlD. 

2 Maximum value for this server given by 
3 5 KamPortGetMaxLogPorts. 

Return Value Type Range Description 

iError short 1 Error flag 

1 iError - 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 
40 KamMiscGetCommandStationlndex takes the controller ID, 

logical port, and a pointer to the location to store the 
maximum index. It sets the memory pointed to by pilndex 
to the specified command station maximum miscellaneous 
data index. 

45 

OKamMiscMaxCont roller ID 

Parameter List Type Range Direction Description 
piMaxControllerlD int * 1-65535 1 Out Maximum 

controller type ID 
50 1 See Figure 6: Controller ID to controller name 

mapping for a list of controller ID values. 0 returned 
on error. 

Return Value Type Range Description 

iError short 1 Error flag 
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1 iError - 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamMiscMaxCont roller ID takes a pointer to the maximum 
controller ID as a parameter. It sets the memory pointed 
to by piMaxControllerlD to the maximum controller type 
ID. 

OKamMiscGetControllerFacility 

Parameter List Type Range Direction Description 
iControllerlD int 1-65535 1 In Command station 

type ID 

pdwFacility long * 2 Out Pointer to command 

station facility mask 
1 See Figure 6: Controller ID to controller name 
mapping for values. Maximum value for this server is 
given by KamMiscMaxControllerlD . 
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Return Value Type Range Description 

iError short 1 Error flag 

1 iError = 0 for success. Nonzero is an error number 
(see KamMiscGetErrorMsg) . 

KamMiscGetControllerFacility takes the controller ID and 
a pointer to the location to store the selected 
controller facility mask. It sets the memory pointed to 
by pdwFacility to the specified command station facility 
mask. 

The digital command stations 18 program the 
digital devices, such as a locomotive and switches, of 
the railroad layout. For example, a locomotive may 
include several different registers that control the 
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horn, how the light blinks, speed curves for operation, 
etc. In many such locomotives there are 106 or more 
programable values. Unfortunately, it may take 1-10 
seconds per byte wide word if a valid register or control 
5 variable (generally referred to collectively as 

registers) and two to four minutes to error out if an 
invalid register to program such a locomotive or device, 
either of which may contain a decoder. With a large 
number of byte wide words in a locomotive its takes 

10 considerable time to fully program the locomotive. 

Further, with a railroad layout including many such 
locomotives and other programmable devices, it takes a 
substantial amount of time to completely program all the 
devices of the model railroad layout. During the 

15 programming of the railroad layout, the operator is 

sitting there not enjoying the operation of the railroad 
layout, is frustrated, loses operating enjoyment, and 
will not desire to use digital programmable devices. In 
addition, to reprogram the railroad layout the operator 

20 must reprogram all of the devices of the entire railroad 
layout which takes substantial time. Similarly, to 
determine the state of all the devices of the railroad 
layout the operator must read the registers of each 
device likewise taking substantial time. Moreover, to 

25 reprogram merely a few bytes of a particular device 

requires the operator to previously know the state of the 
registers of the device which is obtainable by reading 
the registers of the device taking substantial time, 
thereby still frustrating the operator. 

30 The present inventor came to the realization 

that for the operation of a model railroad the 
anticipated state of the individual devices of the 
railroad, as programmed, should be maintained during the 
use of the model railroad and between different uses of 

35 the model railroad. By maintaining data representative 

of the current state of the device registers of the model 
railroad determinations may be made to efficiently 



program the devices. When the user designates a command 
to be executed by one or more of the digital command 
stations 18, the software may determine which commands 
need to be sent to one or more of the digital command 
5 stations 18 of the model railroad. By only updating 

those registers of particular devices that are necessary 
to implement the commands of a particular user, the time 
necessary to program the railroad layout is substantially 
reduced. For example, if the command would duplicate the 

10 current state of the device then no command needs to be 
forwarded to the digital command stations 18. This 
prevents redundantly programming the devices of the model 
railroad, thereby freeing up the operation of the model 
railroad for other activities. 

15 Unlike a single-user single-railroad 

environment, the system of the present invention may 
encounter "conflicting" commands that attempt to write to 
and read from the devices of the model railroad. For 
example, the "conflicting" commands may inadvertently 

2 0 program the same device in an inappropriate manner, such 

as the locomotive to speed up to maximum and the 
locomotive to stop. In addition, a user that desires to 
read the status of the entire model railroad layout will 
monopolize the digital decoders and command stations for 
25 a substantial time, such as up to two hours, thereby 

preventing the enjoyment of the model railroad for the 
other users. Also, a user that programs an extensive 
number of devices will likewise monopolize the digital 
decoders and command stations for a substantial time 

3 0 thereby preventing the enjoyment of the model railroad 

for other users. 

In order to implement a networked selective 
updating technique the present inventor determined that 
it is desirable to implement both a write cache and a 
35 read cache. The write cache contains those commands yet 
to be programmed by the digital command stations 18. 
Valid commands from each user are passed to a queue in 
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the write cache. In the event of multiple commands from 
multiple users (depending on user permissions and 
security) or the same user for the same event or action, 
the write cache will concatenate the two commands into a 
5 single command to be programmed by the digital command 
stations 18. In the event of multiple commands from 
multiple users or the .same user for different events or 
actions, the write cache will concatenate the two 
commands into a single command to be programmed by the 

10 digital command stations 18. The write cache may forward 
either of the commands, such as the last received 
command, to the digital command station. The users are 
updated with the actual . command programmed by the digital 
command station, as necessary. 

15 The read cache contains the state of the 

different devices of the model railroad. After a command 
has been written to a digital device and properly 
acknowledged, if necessary, the read cache is updated 
with the current state of the model railroad. In 

20 addition, the read cache is updated with the state of the 
model railroad when the registers of the devices of the 
model railroad are read. Prior to sending the commands 
to be executed by the digital command stations 18 the 
data in the write cache is compared against the data in 

25 the read cache. In the event that the data in the read 

cache indicates that the data in the write cache does not 
need to be programmed, the command is discarded. In 
contrast, if the data in the read cache indicates that 
the data in the write cache needs to be programmed, then 

3 0 the command is programmed by the digital command station. 
After programming the command by the digital command 
station the read cache is updated to reflect the change 
in the model railroad. As becomes apparent, the use of a 
write cache and a read cache permits a decrease in the 

3 5 number of registers that need to be programmed, thus 

speeding up the apparent operation of the model railroad 
to the operator . 



68 

The present inventor further determined that 
errors in the processing of the commands by the railroad 
and the initial unknown state of the model railroad 
should be taken into account for a robust system. In the 
5 event that an error is received in response to an attempt 
to program (or read) a device, then the state of the 
relevant data of the read cache is marked as unknown. 
The unknown state merely indicates that the state of the 
register has some ambiguity associated therewith. The 

10 unknown state may be removed by reading the current state 
of the relevant device or the data rewritten to the model 
railroad without an error occurring. In addition, if an 
error is received in response to an attempt to program 
(or read) a device, then the command may be re- 

15 transmitted to the digital command station in an attempt 
to program the device properly. If desirable, multiple 
commands may be automatically provided to the digital 
command stations to increase the likelihood of 
programming the appropriate registers. In addition, the 

20 initial state of a register is likewise marked with an 

unknown state until data becomes available regarding its 
state . 

When sending the commands to be executed by the 
digital command stations 18 they are preferably first 

2 5 checked against the read cache, as previously mentioned. 

In the event that the read cache indicates that the state 
is unknown, such as upon initialization or an error, then 
the command should be sent to the digital command station 
because the state is not known. In this manner the state 
30 will at least become known, even if the data in the 
registers is not actually changed. 

The present inventor further determined a 
particular set of data that is useful for a complete 
representation of the state of the registers of the 

3 5 devices of the model railroad. 

An invalid representation of a register 
indicates that the particular register is not 



valid for both a read and a write operation. 
This permits the system to avoid attempting to 
read from and write to particular registers of 
the model railroad. This avoids the 
5 exceptionally long error out when attempting to 

access invalid registers . 

An in use representation of a register 
indicates that the particular register is valid 
10 for both a read and a write operation. This 

permits the system to read from and write to 
particular registers of the model railroad. 
This assists in accessing valid registers where 
the response time is relatively fast. 

15 

A read error (unknown state) representation of 
a register indicates that each time an attempt 
to read a particular register results in an 
error . 

20 

A read dirty representation of a register 
indicates that the data in the read cache has 
not been validated by reading its valid from 
the decoder. If both the read error and the 
25 read dirty representations are clear then a 

valid read from the read cache may be 
performed. A read dirty representation may be 
cleared by a successful write operation, if 
desired . 

30 

A read only representation indicates that the 
register may not be written to. If this flag 
is set then a write error may not occur. 



35 



A write error (unknown state) representation of 
a register indicates that each time an attempt 
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to write to a particular register results in an 
error . 

A write dirty representation of a register 
5 indicates that the data in the write cache has 

not been written to the decoder yet. For 
example, when programming the decoders the 
system programs the data indicated by the write 
dirty. If both the write error and the write 
10 dirty representations are clear then the state 

is represented by the write cache. This 
assists in keeping track of the programming 
without excess overhead. 

15 A write only representation indicates that the 

register may not be read from. If this flag is 
set then a read error may not occur. 

Over time the system constructs a set of 
2 0 representations of the model railroad devices and the 

model railroad itself indicating the invalid registers, 
read errors, and write errors which may increases the 
efficiently of programing and changing the states of the 
model railroad. This permits the system to avoid 

2 5 accessing particular registers where the result will 

likely be an error. 

The present inventor came to the realization 
that the valid registers of particular devices is the 
same for the same device of the same or different model 
30 railroads. Further, the present inventor came to the 
realization that a template may be developed for each 
particular device that may be applied to the 
representations of the data to predetermine the valid 
registers. In addition, the template may also be used to 

3 5 set the read error and write error, if desired. The 

template may include any one or more of the following 
representations, such as invalid, in use, read error, 
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write only, read dirty, read only, write error, and write 
dirty for the possible registers of the device. The 
predetermination of the state of each register of a 
particular device avoids the time consuming activity of 
5 receiving a significant number of errors and thus 

constructing the caches. It is to be noted that the 
actual read and write cache may be any suitable type of 
data structure. 

Many model railroad systems include computer 

10 interfaces to attempt to mimic or otherwise emulate the 
operation of actual full-scale railroads. FIG. 4 
illustrates the organization of train dispatching by 
"timetable and train order" (T&TO) techniques. Many of 
the rules governing T&TO operation are related to the 

15 superiority of trains which principally is which train 
will take siding at the meeting point. Any 
misinterpretation of these rules can be the source of 
either hazard or delay. For example, misinterpreting the 
rules may result in one train colliding with another 

20 train. 

For trains following each other, T&TO operation 
must rely upon time spacing and flag protection to keep 
each train a sufficient distance apart. For example, a 
train may not leave a station less than five minutes 

25 after the preceding train has departed. Unfortunately, 
there is no assurance that such spacing will be retained 
as the trains move along the line, so the flagman (rear 
brakeman) of a train slowing down or stopping will light 
and throw off a five-minute red flare which may not be 

30 passed by the next train while lit. If a train has to 

stop, a flagman trots back along the line with a red flag 
or lantern a sufficient distance to protect the train, 
and remains there until the train is ready to move at 
which time he is called back to the train. A flare and 

3 5 two track torpedoes provide protection as the flagman 

scrambles back and the train resumes speed. While this 
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type of system works, it depends upon a series of human 
activities . 

It is perfectly possible to operate a railroad 
safely without signals. The purpose of signal systems is 
5 not so much to increase safety as it is to step up the 
efficiency and capacity of the line in handling traffic. 
Nevertheless, it's convenient to discuss signal system 
principals in terms of three types of collisions that 
signals are designed to prevent, namely, rear-end, side- 

10 on, and head-on. 

Block signal systems prevent a train from 
ramming the train ahead of it by dividing the main line 
into segments, otherwise known as blocks, and allowing 
only one train in a block at a time, with block signals 

15 indicating whether or not the block ahead is occupied. 

In many blocks, the signals are set by a human operator. 
Before clearing the signal, he must verify that any train 
which has previously entered the block is now clear of 
it, a written record is kept of the status of each block, 

2 0 and a prescribed procedure is used in communicating with 
the next operator. The degree to which a block frees up 
operation depends on whether distant signals (as shown in 
FIG. 5) are provided and on the spacing of open stations, 
those in which an operator is on duty. If as is usually 

2 5 the case it is many miles to the next block station and 

thus trains must be equally spaced. Nevertheless, manual 
block does afford a high degree of safety. 

The block signaling which does the most for 
increasing line capacity is automatic block signals 

3 0 (ABS) , in which the signals are controlled by the trains 

themselves. The presence or absence of a train is 
determined by a track circuit. Invented by Dr. William 
Robinson in 1872, the track circuit's key feature is that 
it is fail-safe. As can be seen in FIG. 6, if the 
35 battery or any wire connection fails, or a rail is 

broken, the relay can't pick up, and a clear signal will 
not be displayed. 
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The track circuit is also an example of what is 
designated in railway signaling practice as a vital 
circuit, one which can give an unsafe indication if some 
of its components malfunction in certain ways. The track 
5 circuit is fail-safe, but it could still give a false 

clear indication should its relay stick in the closed or 
picked-up position. Vital circuit relays, therefore, are 
built to very stringent standards: they are large 
devices; rely on gravity (no springs) to drop their 

10 armature; and use special non-loading contacts which will 
not stick together if hit by a large surge of current 
(such as nearby lightning) . 

Getting a track circuit to be absolutely 
reliable is not a simple matter. The electrical leakage 

15 between the rails is considerable, and varies greatly 

with the seasons of the year and the weather. The joints 
and bolted-rail track are by-passed with bond wire to 
assure low resistance at all times, but the total 
resistance still varies. It is lower, for example, when 

2 0 cold weather shrinks the rails and they pull tightly on 
the track bolts or when hot weather expands to force the 
ends tightly together. Battery voltage is typically 
limited to one or two volts, requiring a fairly sensitive 
relay. Despite this, the direct current track circuit 

25 can be adjusted to do an excellent job and false-clears 
are extremely rare. The principal improvement in the 
basic circuit has been to use slowly-pulsed DC so that 
the relay drops out and must be picked up again 
continually when a block is unoccupied. This allows the 

30 use of a more sensitive relay which will detect a train, 
but additionally work in track circuits twice as long 
before leakage between the rails begins to threaten 
reliable relay operation. Referring to FIGS. 7A and 7B, 
the situations determining the minimum block length for 

35 the standard two-block, three-indication ABS system. 

Since the train may stop with its rear car just inside 
the rear boundary of a block, a following train will 
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first receive warning just one block- length away. No 
allowance may be made for how far the signal indication 
may be seen by the engineer. Swivel block must be as 
long as the longest stopping distance for any train on 
5 the route, traveling at its maximum authorized speed. 

From this standpoint, it is important to allow 
trains to move along without receiving any approach 
indications which will force them to slow down. This 
requires a train spacing of two block lengths, twice the 

10 stopping distance, since the signal can't clear until the 
train ahead is completely out of the second block. When 
fully loaded trains running at high speeds, with their 
stopping distances, block lengths must be long, and it is 
not possible to get enough trains over the line to 

15 produce appropriate revenue . 

The three -block, four- indication signaling 
shown in FIG. 7 reduces the excess train spacing by 50% 
with warning two blocks to the rear and signal spacing 
need be only 1/2 the braking distance. In particularly 

2 0 congested areas such as downgrades where stopping 

distances are long and trains are likely to bunch up, 
four-block, four-indication signaling may be provided and 
advanced approach, approach medium, approach and stop 
indications give a minimum of three-block warning, 

25 allowing further block-shortening and keeps things 
moving . 

FIG. 8 uses aspects of upper quadrant 
semaphores to illustrate block signaling. These signals 
use the blade rising 90 degrees to give the clear 
30 indication. 

Some of the systems that are currently 
developed by different railroads are shown in FIG. 8. 
With the general rules discussed below, a railroad is 
free to establish the simplest and most easily maintained 
35 system of aspects and indications that will keep traffic 
moving safely and meet any special requirements due to 
geography, traffic pattern, or equipment. Aspects such 
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as flashing yellow for approach medium, for example, may 
be used to provide an extra indication without an extra 
signal head. This is safe because a stuck flasher will 
result in either a steady yellow approach or a more 
5 restrictive light-out aspect. In addition, there are 

provisions for interlocking so the trains may branch from 
one track to another. 

To take care of junctions where trains are 
diverted from one route to another, the signals must 

10 control train speed. The train traveling straight 

through must be able to travel at full speed. Diverging 
routes will require some limit, depending on the turnout 
members and the track curvature, and the signals must 
control train speed to match. One approach is to have 

15 signals indicate which route has been set up and cleared 
for the train. In the American approach of speed 
signaling, in which the signal indicates not where the 
train is going but rather what speed is allowed through 
the interlocking. If this is less than normal speed, 

20 distant signals must also give warning so the train can 
be brought down to the speed in time. FIGS. 9A and 9B 
show typical signal aspects and indications as they would 
appear to an engineer. Once a route is established and 
the signal cleared, route locking is used to insure that 

2 5 nothing can be changed to reduce the route's speed 

capability from the time the train approaching it is 
admitted to enter until it has cleared the last switch. 
Additional refinements to the basic system to speed up 
handling trains in rapid sequence include sectional route 

3 0 locking which unlocks portions of the route as soon as 

the train has cleared so that other routes can be set up 
promptly. Interlocking signals also function as block 
signals to provide rear-end protection. In addition, at 
isolated crossings at grade, an automatic interlocking 
35 can respond to the approach of a train by clearing the 
route if there are no opposing movements cleared or in 
progress. Automatic interlocking returns everything to 



76 

stop after the train has passed. As can be observed, the 
movement of multiple trains among the track potentially 
involves a series of interconnected activities and 
decisions which must be performed by a controller, such 
5 as a dispatcher. In essence, for a railroad the 

dispatcher controls the operation of the trains and 
permissions may be set by computer control , thereby 
controlling the railroad. Unfortunately, if the 
dispatcher fails to obey the rules as put in place, 

10 traffic collisions may occur. 

In the context of a model railroad the 
controller is operating a model railroad layout including 
an extensive amount of track, several locomotives 
(trains), and additional functionality such as switches. 

15 The movement of different obj ects , such as locomotives 

and entire trains, may be monitored by a set of sensors. 
The operator issues control commands from his computer 
console, such as in the form of permissions and class 
warrants for the time and track used. In the existing 

20 monolithic computer systems for model railroads a single 
operator from a single terminal may control the system 
effectively. Unfortunately, the present inventor has 
observed that in a multi-user environment where several 
clients are attempting to simultaneously control the same 

25 model railroad layout using their terminals, collisions 
periodically nevertheless occur. In addition, 
significant delay is observed between the issuance of a 
command and its eventual execution. The present inventor 
has determined that unlike full scale railroads where the 

30 track is controlled by a single dispatcher, the use of 
multiple dispatchers each having a different dispatcher 
console may result in conflicting information being sent 
to the railroad layout. In essence, the system is 
designed as a computer control system to implement 

3 5 commands but in no manner can the dispatcher consoles 

control the actions of users. For example, a user input 
may command that an event occur resulting in a crash. In 
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addition, a user may override the block permissions or 
class warrants for the time and track used thereby 
causing a collision. In addition, two users may 
inadvertently send conflicting commands to the same or 
5 different trains thereby causing a collision. In such a 
system, each user is not aware of the intent and actions 
of other users aside from any feedback that may be 
displayed on their terminal. Unfortunately, the feedback 
to their dispatcher console may be delayed as the 

10 execution of commands issued by one or more users may 

take several seconds to several minutes to be executed. 

One potential solution to the dilemma of 
managing several users 1 attempt to simultaneously control 
a single model railroad layout is to develop a software 

15 program that is operating on the server which observes 
what is occurring. In the event that the software 
program determines that a collision is imminent, a stop 
command is issued to the train overriding all other 
commands to avoid such a collision. However, once the 

20 collision is avoided the user may, if desired, override 

such a command thereby restarting the train and causing a 
collision. Accordingly, a software program that merely 
oversees the operation of track apart from the validation 
of commands to avoid imminent collisions is not a 

2 5 suitable solution for operating a model railroad in a 

multi-user distributed environment. The present inventor 
determined that prior validation is important because of 
the delay in executing commands on the model railroad and 
the potential for conflicting commands. In addition, a 

3 0 hardware throttle directly connected to the model 

railroad layout may override all such computer based 
commands thereby resulting in the collision. Also, this 
implementation provides a suitable security model to use 
for validation of user actions. 
35 Referring to FIG. 10, the client program 14 

preferably includes a control panel 3 00 which provides a 
graphical interface (such as a personal computer with 
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software thereon or a dedicated hardware source) for 
computerized control of the model railroad 302. The 
graphical interface may take the form of those 
illustrated in FIGS. 5-9, or any other suitable command 
5 interface to provide control commands to the model 

railroad 302. Commands are issued by the client program 
14 to the controlling interface using the control panel 
300. The commands are received from the different client 
programs 14 by the controlling interface 16. The 

10 commands control the operation of the model railroad 302, 
such as switches, direction, and locomotive throttle. Of 
particular importance is the throttle which is a state 
which persists for an indefinite period of time, 
potentially resulting in collisions if not accurately 

15 monitored. The controlling interface 16 accepts all of 
the commands and provides an acknowledgment to free up 
the communications transport for subsequent commands. 
The acknowledgment may take the form of a response 
indicating that the command was executed thereby updating 

2 0 the control panel 3 00. The response may be subject to 

updating if more data becomes available indicating the 
previous response is incorrect. In fact, the command may 
have yet to be executed or verified by the controlling 
interface 16. After a command is received by the 
25 controlling interface 16, the controlling interface 16 

passes the command (in a modified manner, if desired) to 
a dispatcher controller 310. The dispatcher controller 
310 includes a rule-based processor together with the 
layout of the railroad 3 02 and the status of objects 

3 0 thereon. The objects may include properties such as 

speed, location, direction, length of the train, etc. 
The dispatcher controller 310 processes each received 
command to determine if the execution of such a command 
would violate any of the rules together with the layout 
35 and status of objects thereon. If the command received 
is within the rules, then the command may be passed to 
the model railroad 3 02 for execution. If the received 
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command violates the rules, then the command may be 
rejected and an appropriate response is provided to 
update the clients display. If desired, the invalid 
command may be modified in a suitable manner and still be 
5 provided to the model railroad 302. In addition, if the 
dispatcher controller 310 determines that an event should 
occur, such as stopping a model locomotive, it may issue 
the command and update the control panels 3 00 
accordingly. If necessary, an update command is provided 
10 to the client program 14 to show the update that 
occurred. 

The "asynchronous" receipt of commands together 
with a "synchronous" manner of validation and execution of 
commands from the multiple control panels 300 permits a 
15 simplified dispatcher controller 310 to be used together 
with a minimization of computer resources, such as com 
ports. In essence, commands are managed independently 
from the client program 14. Likewise, a centralized 
dispatcher controller 310 working in an "off-line" mode 

2 0 increases the likelihood that a series of commands that 

are executed will not be conflicting resulting in an 
error. This permits multiple model railroad enthusiasts 
to control the same model railroad in a safe and 
efficient manner. Such concerns regarding the 
25 interrelationships between multiple dispatchers does not 
occur in a dedicated non-distributed environment. When 
the command is received or validated all of the control 
panels 300 of the client programs 14 may likewise be 
updated to reflect the change. Alternatively, the 

3 0 controlling interface 16 may accept the command, validate 

it quickly by the dispatcher controller, and provide an 
acknowledgment to the client program 14. In this manner, 
the client program 14 will not require updating if the 
command is not valid. In a likewise manner, when a 
35 command is valid the control panel 300 of all client 

programs 14 should be updated to show the status of the 
model railroad 302. 
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f A manual throttle 320 may likewise provide 

control over devices, such as the locomotive, on the 
model railroad 302. The commands issued by the manual 
throttle 320 may be passed first to the dispatcher 
5 controller 310 for validation in a similar manner to that 
of the client programs 14. Alternatively, commands from 
the manual throttle 320 may be directly passed to the 
model railroad 302 without first being validated by the 
dispatcher controller 302. After execution of commands 

10 by the external devices 18, a response will be provided 
to the controlling interface 16 which in response may 
check the suitability of the command, if desired. If the 
command violates the layout rules then a suitable 
correctional command is issued to the model railroad 302. 

15 If the command is valid then no correctional command is 
necessary. In either case, the status of the model 
railroad 3 02 is passed to the client programs 14 (control 
panels 300) . 

As it can be observed, the event driven 

20 dispatcher controller 310 maintains the current status of 
the model railroad 302 so that accurate validation may be 
performed to minimize conflicting and potentially 
damaging commands. Depending on the particular 
implementation, the control panel 300 is updated in a 

25 suitable manner, but in most cases, the communication 
transport 12 is freed up prior to execution of the 
command by the model railroad 302. 

The computer dispatcher may also be distributed 
across the network, if desired. In addition, the 

30 computer architecture described herein supports different 
computer interfaces at the client program 14. 

The terms and expressions which have been 
employed in the foregoing specification are used therein 
as terms of description and not of limitation, and there 

35 is no intention, in the use of such terms and 

expressions, of excluding equivalents of the features 
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shown and described or portions thereof, it being 
recognized that the scope of the invention is defined and 
limited only by the claims which follow. 



